Skip to content

Commit

Permalink
fix unit tests; code style
Browse files Browse the repository at this point in the history 
docs
fix 'failover' plugin for GDB; add PG support for GDB
adopt GDB support including Global Writer Endpoint to failover2
  • Loading branch information
@sergiyvamz
sergiyvamz committed Jan 22, 2025
1 parent 832e871 commit 8a9a7e6
Show file tree
Hide file tree
Showing 28 changed files with 813 additions and 248 deletions.
10 changes: 5 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ With the `failover` plugin, the downtime during certain DB cluster operations, s

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

### Using the WS JDBC Driver with Amazon Aurora Global Databases

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.

### Using the AWS JDBC Driver with plain RDS databases
The AWS JDBC Driver also works with RDS provided databases that are not Aurora.

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

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

#### Amazon Aurora Global Databases

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.

## Examples

| Description | Examples |
Expand All @@ -153,7 +153,7 @@ This driver currently does not support `planned failover` or `switchover` of Ama
| Using Spring and Wildfly with the AWS JDBC Driver | [PostgreSQL](examples/SpringWildflyExample/README.md) |
| Using Vert.x and c3p0 with the AWS JDBC Driver | [PostgreSQL](examples/VertxExample/README.md) |
| 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) |
| Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsXRayExample.java) |
| Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon | [PostgreSQL](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryTracingXRayExample.java) |

## Getting Help and Opening Issues
If you encounter a bug with the AWS JDBC Driver, we would like to hear about it.
Expand Down
2 changes: 2 additions & 0 deletions ...-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ When this plugin is enabled, if the initial connection is to a reader cluster en

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.

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.

## Enabling the Aurora Initial Connection Strategy Plugin

To enable the Aurora Initial Connection Strategy Plugin, add `initialConnection` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value.
Expand Down
3 changes: 2 additions & 1 deletion docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ In addition to the parameters that you can configure for the underlying driver,
| Parameter | Value | Required | Description | Default Value |
|---------------------------------------|:-------:|:--------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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`. |
| `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. |
| `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. |
| `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). | |
| `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` |
| `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` |
| `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` |
Expand Down
Loading

0 comments on commit 8a9a7e6

Please sign in to comment.