Skip to content

Commit 8a9a7e6

Browse files
sergiyvamzsergiyvamz
committed
fix unit tests; code style
docs fix 'failover' plugin for GDB; add PG support for GDB adopt GDB support including Global Writer Endpoint to failover2
1 parent 832e871 commit 8a9a7e6

28 files changed

+813
-248
lines changed

‎README.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ With the `failover` plugin, the downtime during certain DB cluster operations, s
3737

3838
Visit [this page](./docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md) for more details.
3939

40+
### Using the WS JDBC Driver with Amazon Aurora Global Databases
41+
42+
This driver supports in-region `failover` and between-regions `planned failover` and `switchover` of [Amazon Aurora Global Databases](https://aws.amazon.com/ru/rds/aurora/global-database/). A [Global Writer Endpoint](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-connecting.html) is also recognized and can be substituted with a current writer instance endpoint to minimize potential stale DNS issue. Please check [failover plugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md), [failover2 plugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md) and [Aurora Initial Connection Strategy plugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md) for more information.
43+
4044
### Using the AWS JDBC Driver with plain RDS databases
4145
The AWS JDBC Driver also works with RDS provided databases that are not Aurora.
4246

@@ -128,10 +132,6 @@ The development team is aware of these limitations and is working to improve the
128132

129133
[^1]: Aurora MySQL requires v3.07 or later.
130134

131-
#### Amazon Aurora Global Databases
132-
133-
This driver currently does not support `planned failover` or `switchover` of Amazon Aurora Global Databases. Failing over to a secondary cluster will result in errors and there may be additional unforeseen errors when working with global databases. Connecting to the primary cluster is fully supported. There is a limitation when connected to the secondary cluster; the [failover2 plugin](using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin) will not work on the secondary cluster, however the [failover plugin](using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin) will work. Full Support for Amazon Aurora Global Databases is in the backlog, but we cannot comment on a timeline right now.
134-
135135
## Examples
136136

137137
| Description | Examples |
@@ -153,7 +153,7 @@ This driver currently does not support `planned failover` or `switchover` of Ama
153153
| Using Spring and Wildfly with the AWS JDBC Driver | [PostgreSQL](examples/SpringWildflyExample/README.md) |
154154
| Using Vert.x and c3p0 with the AWS JDBC Driver | [PostgreSQL](examples/VertxExample/README.md) |
155155
| Using the AWS JDBC Driver with Telemetry and using the AWS Distro for OpenTelemetry Collector | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsOTLPExample.java) |
156-
| Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsXRayExample.java) |
156+
| Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryTracingXRayExample.java) |
157157

158158
## Getting Help and Opening Issues
159159
If you encounter a bug with the AWS JDBC Driver, we would like to hear about it.

‎docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ When this plugin is enabled, if the initial connection is to a reader cluster en
55

66
This plugin also helps retrieve connections more reliably. When a user connects to a cluster endpoint, the actual instance for a new connection is resolved by DNS. During failover, the cluster elects another instance to be the writer. While DNS is updating, which can take up to 40-60 seconds, if a user tries to connect to the cluster endpoint, they may be connecting to an old node. This plugin helps by replacing the out of date endpoint if DNS is updating.
77

8+
In case of Aurora Global Database, a user has an option to use an [Aurora Global Writer Endpoint](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-connecting.html). Global Writer Endpoint makes a user application configuration easier. However, similar to a cluster writer endpoint mentioned above, it can also be affected by DNS updates. The Aurora Initial Connection Strategy Plugin recognizes an Aurora Global Writer Endpoint and substitutes it with a current writer endpoint.
9+
810
## Enabling the Aurora Initial Connection Strategy Plugin
911

1012
To enable the Aurora Initial Connection Strategy Plugin, add `initialConnection` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value.

‎docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@ In addition to the parameters that you can configure for the underlying driver,
5757
| Parameter | Value | Required | Description | Default Value |
5858
|---------------------------------------|:-------:|:--------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
5959
| `failoverMode` | String | No | Defines a mode for failover process. Failover process may prioritize nodes with different roles and connect to them. Possible values: <br><br>- `strict-writer` - Failover process follows writer node and connects to a new writer when it changes.<br>- `reader-or-writer` - During failover, the driver tries to connect to any available/accessible reader node. If no reader is available, the driver will connect to a writer node. This logic mimics the logic of the Aurora read-only cluster endpoint.<br>- `strict-reader` - During failover, the driver tries to connect to any available reader node. If no reader is available, the driver raises an error. Reader failover to a writer node will only be allowed for single-node clusters. This logic mimics the logic of the Aurora read-only cluster endpoint.<br><br>If this parameter is omitted, default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | Default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. |
60-
| `clusterInstanceHostPattern` | String | If connecting using an IP address or custom domain URL: Yes<br><br>Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](#host-pattern) for more information. <br/><br/>Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`<br/><br/>Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection string should look like this: `jdbc:aws-wrapper:mysql://customHost:1234/test?clusterInstanceHostPattern=?.customHost` | If the provided connection string is not an IP address or custom domain, the JDBC Driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. |
60+
| `clusterInstanceHostPattern` | String | If connecting using an IP address or custom domain URL: Yes<br><br>Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](./UsingTheFailoverPlugin.md#host-pattern) for more information. <br/><br/> This parameter is ignored for Aurora Global Databases. <br/><br/>Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`<br/><br/>Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection string should look like this: `jdbc:aws-wrapper:mysql://customHost:1234/test?clusterInstanceHostPattern=?.customHost` | If the provided connection string is not an IP address or custom domain, the JDBC Driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. |
61+
| `globalClusterInstanceHostPatterns` | String | For Global Databases: Yes <br><br>Otherwise: No | This parameter is similar to `clusterInstanceHostPattern` parameter but it provides a coma-separated list of instance host patterns. This parameter is required for Aurora Global Databases. The list should contains host pattern for each region of a global database. Each host pattern should be based on an instance endpoint. Custom domain URLs are not supported. <br/><br/> The parameter is ignored for other types of databases (Aurora Clusters, RDS Clusters, plain RDS databases, etc.).<br/><br/>Example: for an Aurora Global Database with two AWS regions `us-east-2` and `us-west-2`, the parameter value is `?.XYZ1.us-east-2.rds.amazonaws.com,?.XYZ2.us-west-2.rds.amazonaws.com`. Please pay attention that user identifiers are different for different AWS regions (`XYZ1` and `XYZ2` as in the example above). | |
6162
| `clusterTopologyRefreshRateMs` | Integer | No | Cluster topology refresh rate in milliseconds when a cluster is not in failover. It refers to the regular, slow monitoring rate explained above. | `30000` |
6263
| `failoverTimeoutMs` | Integer | No | Maximum allowed time in milliseconds to attempt reconnecting to a new writer or reader instance after a cluster failover is initiated. | `300000` |
6364
| `clusterTopologyHighRefreshRateMs` | Integer | No | Interval of time in milliseconds to wait between attempts to update cluster topology after the writer has come back online following a failover event. It corresponds to the increased monitoring rate described earlier. Usually, the topology monitoring component uses this increased monitoring rate for 30s after a new writer was detected. | `100` |

0 commit comments

Comments
 (0)