The AWS Advanced JDBC Wrapper uses the GDB Failover Plugin to provide minimal downtime in the event of a DB instance failure. The plugin is based on Failover Plugin v2 and unless explicitly stated otherwise, most of the information and suggestions for the Failover Plugin and Failover Plugin v2 are applicable to the GDB Failover Plugin.
The plugin is available since version 3.2.0.
The GDB Failover Plugin introduces the notion of home region and extends configuration parameters to allow setting different failover logic for in-home and out-of-home cases.
Driver configuration for the GDB failover plugin should include a home region defined with an AWS region name. This introduces two cases:
- in-home: when the primary region of the Global Database is the same as the specified home region
- out-of-home: when GDB switches over to another region and the primary region is not the same as the specified home region.
Users are allowed to specify different failover logic individually for in-home and out-of-home cases. The following are two examples where in-home and out-of-home cases impact the failover logic.
Example 1
When a user application needs a writer connection, it makes sense to define the failover mode to follow the writer (strict-writer). However, some applications may choose not to follow a writer node when cross-region failover occurs (see Configuration Example 3 below).
- in-home: when in-region failover occurs, the driver reconnects to a new writer node and continues serving the user application with a write connection.
- out-of-home: application turns to inactive mode and stops performing writes, this prioritizes performance due to reduced connection latency over being connected to a writer node in another region.
Example 2
When a user application needs a reader connection, prioritize reader connections in the home region to reduce connection latency (see Configuration Example 2 below).
- in-home: the primary region of the Global Database is the same as the specified home region, connect to any such reader.
- out-of-home: connect to readers that are in the specified home region, these readers are no longer part of the primary region of the Global Database.
The mentioned scenarios can be configured with the GDB Failover plugin. Failover2 Plugin and Failover Plugin don't support the home region and can't be used for the cases mentioned above.
The GDB Failover Plugin will not be enabled by default if the wrapperPlugins value is not specified. If you would like to override the default plugins, you can explicitly include the GDB Failover Plugin in your list of plugins by adding the plugin code gdbFailover to the wrapperPlugins value, or by adding it to the current driver profile. After you load the plugin, the failover feature will be enabled.
Please refer to the failover configuration guide for tips to keep in mind when using the failover plugin.
Warning
Do not use the gdbFailover, failover and/or failover2 plugins (or their combination) at the same time for the same connection!
Verify plugin compatibility within your driver configuration using the compatibility guide.
In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters for the AWS Advanced JDBC Wrapper through the connection URL to specify additional failover behavior.
| Parameter | Value | Required | Description | Default Value |
|---|---|---|---|---|
failoverHomeRegion |
String | If connecting using an IP address, a custom domain URL, Global Database endpoint or other endpoint with no region: Yes Otherwise: No |
Defines a home region. Examples: us-west-2, us-east-1. If this parameter is omitted, the value is parsed from connection url. For regional cluster endpoints and instance endpoints, it's set to the region of the provided endpoint. If the provided endpoint has no region (for example, a Global Database endpoint or IP address) the configuration parameter is mandatory. |
|
activeHomeFailoverMode |
String | No | Defines a mode for failover process when GDB primary region is home region. Failover process may prioritize nodes with different roles and connect to them. Possible values: - strict-writer - Failover process follows writer node and connects to a new writer (in any region) when it changes.- home-reader-or-writer - During failover, the driver tries to connect to any available/accessible reader node in home region. If no reader is available, the driver will connect to a writer node (in any region).- strict-home-reader - During failover, the driver tries to connect to any available reader node in home region. If no reader is available, the driver raises an error.- strict-out-of-home-reader, strict-any-reader, out-of-home-reader-or-writer, any-reader-or-writer - other possible values with prioritizing different writer or reader nodes in home, out of home, or in any region.If this parameter is omitted, default value depends on connection url. For Aurora writer cluster endpoint or Global Database endpoint, it's set to strict-writer. Otherwise, it's home-reader-or-writer. |
Default value depends on connection url. For Aurora writer cluster endpoint or Global Database endpoint, it's set to strict-writer. Otherwise, it's home-reader-or-writer. |
inactiveHomeFailoverMode |
String | No | Defines a mode for failover process when GDB primary region is not a home region. Possible values are the same as for activeHomeFailoverMode parameter: strict-writer, home-reader-or-writer, strict-home-reader, strict-out-of-home-reader, strict-any-reader, out-of-home-reader-or-writer, any-reader-or-writer.If this parameter is omitted, default value depends on connection url. For Aurora writer cluster endpoint or Global Database endpoint, it's set to strict-writer. Otherwise, it's home-reader-or-writer. |
Default value depends on connection url. For Aurora writer cluster endpoint or Global Database endpoint, it's set to strict-writer. Otherwise, it's home-reader-or-writer. |
clusterInstanceHostPattern |
String | If connecting using an IP address or custom domain URL: Yes 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 for more information. Example: ?.my-domain.com, any-subdomain.?.my-domain.com:9999Use 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 Otherwise: No |
This parameter is similar to the clusterInstanceHostPattern parameter but it provides a comma-separated list of instance host patterns. This parameter is required for Aurora Global Databases. The list should contain host patterns for each region of the global database. Each host pattern can be based on an RDS instance endpoint or a custom user domain name. If a custom domain name is used, the instance template pattern should be prefixed with the AWS region name in square brackets ([<aws-region-name>]). The parameter is ignored for other types of databases (Aurora Clusters, RDS Clusters, plain RDS databases, etc.). Example: for an Aurora Global Database with two AWS regions us-east-2 and us-west-2, the parameter value should be set to ?.XYZ1.us-east-2.rds.amazonaws.com,?.XYZ2.us-west-2.rds.amazonaws.com. Please note that user identifiers are different for different AWS regions (XYZ1 and XYZ2 in the example above). Example: if using custom domain names, the parameter value should be similar to [us-east-2]?.customHost,[us-west-2]?.anotherCustomHost. The port can also be provided: [us-east-2]?.customHost:8888,[us-west-2]?.anotherCustomHost:9999 For complete Aurora Global Database configuration, see Aurora Global Databases. |
|
clusterTopologyRefreshRateMs |
Integer | No | Cluster topology refresh rate in milliseconds when a cluster is not in failover. It refers to the regular slow monitoring rate described in Failover Plugin v2. | 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 in Failover Plugin v2. Usually, the topology monitoring component uses this increased monitoring rate for 30s after a new writer was detected. | 100 |
failoverReaderHostSelectorStrategy |
String | No | Strategy used to select a reader node during failover. For more information on the available reader selection strategies, see this table. | random |
clusterId |
String |
If connecting to multiple database clusters within a single application:: Yes Otherwise: No |
A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. This parameter is optional and defaults to 1. When supporting multiple database clusters, this parameter becomes mandatory. Each connection string must include the clusterId parameter with a value that can be any number or string. However, all connection strings associated with the same database cluster must use identical clusterId values, while connection strings belonging to different database clusters must specify distinct values. Examples of value: 1, 2, 1234, abc-1, abc-2. |
1 |
telemetryFailoverAdditionalTopTrace |
Boolean | No | Allows the driver to produce an additional telemetry span associated with failover. Such span helps to facilitate telemetry analysis in AWS CloudWatch. | false |
skipFailoverOnInterruptedThread |
Boolean | No | Enable to skip failover if the current thread is interrupted. This may leave the Connection in an invalid state so the Connection should be disposed. | false |
skipInactiveWriterClusterEndpointCheck |
Boolean | No | Enable to skip a connection role verification when connection is opened with inactive cluster writer endpoint. This parameter is applicable to Aurora Global Databases. Region-bound cluster writer endpoints are available in Global Databases. However, depending on the GDB primary region, they may be inactive and may act differently. The parameter is aimed at supporting such inactive cluster endpoints and helps configure the desired behavior for them. | false |
Please refer to the original Failover Plugin and Failover2 Plugin for more details about error codes, configurations, connection pooling and sample codes.
PostgreSQL Failover Sample Code
This sample code uses the original failover plugin, but it can also be used with the gdbFailover plugin. Configuration parameters should be adjusted in accordance with the table above.
Goal: Provide a user application with a writer connection. The application is deployed in us-west-1 region and connects to Global Database with us-east-1, us-east-2 and us-west-1 regions.
Solution: Use the following configuration parameters to configure the driver:
failoverHomeRegion=us-west-1activeHomeFailoverMode=strict-writerinactiveHomeFailoverMode=strict-writerglobalClusterInstanceHostPatterns=?.XYZ1.us-east-1.rds.amazonaws.com,?.XYZ2.us-east-2.rds.amazonaws.com,?.XYZ3.us-west-1.rds.amazonaws.com(make sure you replaceXYZ1,XYZ2,XYZ3with actual values that correspond to your database)wrapperDialect=global-aurora-mysql(orglobal-aurora-pg)wrapperPlugins=initialConnection,gdbFailover,efm2- use Global Database endpoint in your connection string
Goal: Provide a user application with a reader connection in us-west-1. The application is deployed in the us-west-1 region and connects to a Global Database with us-east-1, us-east-2 and us-west-1 regions. If the GDB primary region switches over, prioritize reader connections from the us-west-1 region.
Solution: Use the following configuration parameters to configure the driver:
failoverHomeRegion=us-west-1activeHomeFailoverMode=strict-home-readerinactiveHomeFailoverMode=strict-home-readerglobalClusterInstanceHostPatterns=?.XYZ1.us-east-1.rds.amazonaws.com,?.XYZ2.us-east-2.rds.amazonaws.com,?.XYZ3.us-west-1.rds.amazonaws.com(make sure you replaceXYZ1,XYZ2,XYZ3with actual values that correspond to your database)wrapperDialect=global-aurora-mysql(orglobal-aurora-pg)wrapperPlugins=initialConnection,gdbFailover,efm2- use cluster reader endpoint in region
us-west-1in your connection string (<cluster-name>.cluster-ro-XYZ3.us-west-1.rds.amazonaws.com)
Goal: Provide a user application with a writer connection when the primary region is the closest to the application deployed region. When the primary region switches over to another region and network latency becomes unacceptable, the application deployment in region us-west-1 becomes inactive and lets applications in other regions act and process business transactions. There are application deployments in other regions. The Global Database has us-east-1, us-east-2 and us-west-1 regions.
Solution: Use the following configuration parameters to configure the driver for application deployment in the us-west-1 region. Other application deployments need similar driver configuration with different home regions.
failoverHomeRegion=us-west-1activeHomeFailoverMode=strict-writerinactiveHomeFailoverMode=strict-any-readerglobalClusterInstanceHostPatterns=?.XYZ1.us-east-1.rds.amazonaws.com,?.XYZ2.us-east-2.rds.amazonaws.com,?.XYZ3.us-west-1.rds.amazonaws.com(make sure you replaceXYZ1,XYZ2,XYZ3with actual values that correspond to your database)wrapperDialect=global-aurora-mysql(orglobal-aurora-pg)wrapperPlugins=initialConnection,gdbFailover,efm2- use cluster writer endpoint in region
us-west-1in your connection string (<cluster-name>.cluster-XYZ3.us-west-1.rds.amazonaws.com)
Explanation: While the primary region of GDB is us-west-1, the application deployed in this region needs writable connections. By using the cluster writer endpoint, the driver opens connections to a writer node. If in-region failover occurs, the driver reconnects to a new writer node in the same us-west-1 region. Since after GDB failover the writer node is in the same region, the driver considers this case as in-home and effectively uses the activeHomeFailoverMode=strict-writer setting. Following the writer node for in-region failovers helps the application deployment in the us-west-1 region to process business transactions with minimal latency. When a cross-region failover event occurs, the driver detects a new writer node, let's assume it's in the us-east-1 region, and uses the inactiveHomeFailoverMode=strict-any-reader setting. The driver serves a reader connection from any available region us-east-1, us-east-2 and us-west-1.
Warning
This example covers failover and failover-related settings only. Complete driver configuration may require settings for other plugins. For instance, initialConnection may require endpointSubstitutionRole and verifyOpenedConnectionType parameters to be set properly.