The Aurora Initial Connection Strategy Plugin allows users to configure their initial connection strategy, and it can also be used to obtain a connection more reliably if DNS is updating by replacing an outdated endpoint. When the Aurora Initial Connection Strategy Plugin attempts to make a connection, it may retry the connection attempt if there is a failure. Users are able to configure how often to retry a connection and the maximum allowed time to obtain a connection using the connection parameters.
When this plugin is enabled, if the initial connection is to a reader cluster or custom cluster endpoint, the connected host will be chosen based on the configured strategy. The initial connection strategy specifies how the driver determines which available reader to connect to.
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 outdated endpoint if DNS is updating.
When using Aurora Global Database, the user has an option to use an Aurora Global Writer Endpoint. The Global Writer Endpoint makes a user application configuration easier. However, similar to the 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 the current writer endpoint.
For detailed Aurora Global Database configuration, see Aurora Global Databases.
Verify plugin compatibility within your driver configuration using the compatibility guide.
The plugin is available since version 2.3.1.
To enable the Aurora Initial Connection Strategy Plugin, add initialConnection to the
wrapperPlugins value.
The following properties can be used to configure the Aurora Initial Connection Strategy Plugin.
Note
For an in-depth explanation of gdbAccessibleRegions, see Restricting Aurora Global Database Access by Region.
| Parameter | Value | Required | Description | Example | Default Value |
|---|---|---|---|---|---|
readerInitialConnectionHostSelectorStrategy |
String | No | Deprecated. Use initialConnectionHostSelectorStrategy instead. During migration period, the value of parameter readerInitialConnectionHostSelectorStrategy will be used when new parameter initialConnectionHostSelectorStrategy is omitted. The strategy that will be used to select a new reader host when opening a new connection. For more information on the available reader selection strategies, see this table. |
leastConnections |
random |
endpointSubstitutionRole |
String | No | Defines whether or not the initial connection URL should be replaced with an instance URL from the topology info when available, and if so, the role of the instance URL that should be selected. This property should only be set if using a URL that resolves to a cluster URL (global writer, writer, reader, or custom). This behavior can improve the chances of connecting to the correct role. It also can be used in conjunction with initialConnectionHostSelectorStrategy to load balance instances according to a host selector strategy when multiple instances with the matching role exist.For writer cluster endpoints or global writer endpoints, valid values are writer and none. For reader endpoints valid values are reader and none. For custom cluster endpoints with the custom endpoint plugin enabled, valid values are any, reader, or none. If you are using custom cluster endpoints without the custom endpoint plugin enabled, the only valid value is none. If the value is set to none, the initial URL will not be replaced. Explicitly setting the parameter overrides the default behavior. |
reader |
writer when using writer cluster endpoints or global writer cluster endpoints.reader when using reader cluster endpoints.none when using custom cluster endpoints.Otherwise: none. |
initialConnectionHostSelectorStrategy |
String | No | The strategy that will be used to select a host when opening a new connection. A host will be selected according to the host role specified in parameter endpointSubstitutionRole. If endpointSubstitutionRole isn't provided then any available host will be selected by the strategy.For more information on the available host selection strategies, see this table. |
leastConnections |
random |
verifyOpenedConnectionType |
String | No | Defines whether an opened connection should be verified to be a writer or reader after connecting, or if no role verification should be performed. For writer endpoints or global writer endpoints, valid values are writer and none. For reader endpoints and custom endpoints possible values are reader and none. In other cases possible values are reader,writer and none. The value none defines no host role verification. Explicitly setting the parameter overrides the default behavior. |
reader |
writer when using writer cluster endpoints or global cluster endpoints.reader when using reader cluster endpoints.Otherwise: none. |
openConnectionRetryTimeoutMs |
Integer | No | The maximum allowed time for retries when opening a connection in milliseconds. | 40000 |
30000 |
openConnectionRetryIntervalMs |
Integer | No | The time between retries when opening a connection in milliseconds. | 2000 |
1000 |
waitForInitialTopologyMs |
Long | No | Available since version 4.1.0. The maximum allowed time, in milliseconds, to wait for the cluster topology to be fetched before opening a new connection. When set to a value greater than 0 and the topology is not yet available, the plugin blocks until the topology has been discovered (or this timeout is reached) instead of falling back to connecting via the cluster endpoint. This ensures that host selection strategies such as roundRobin distribute concurrent and connection-pool prefill connections across instances, rather than routing them all to a single instance resolved through DNS.The wait is scoped to the cluster the connection belongs to; connections to other clusters are not affected. Concurrent connections to the same cluster share a single topology fetch rather than each issuing their own. On timeout, the plugin falls back to the previous behavior of connecting via the provided endpoint. When set to 0 (the default), the previous behavior is preserved.Enabling this adds a one-time latency to the first connection (or the first few connections during a pool prefill) while topology is being fetched. |
30000 |
0 |
inactiveClusterWriterEndpointSubstitutionRole |
String | No | Defines whether or not the inactive cluster writer endpoint in the initial connection URL should be replaced with a writer instance URL from the topology info when available. 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. Valid values are writer and none. |
writer |
writer |
verifyInactiveClusterWriterEndpointConnectionType |
String | No | Defines whether a connection opened with inactive cluster writer endpoint in the initial connection URL should be verified to be a writer, or if no role verification should be performed. 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. Valid values are writer and none. |
writer |
writer |
gdbAccessibleRegions |
String | No | Available since version 4.1.0. Comma-separated list of AWS regions accessible by the application. When set and the dialect is a Global Aurora dialect (e.g., global-aurora-mysql or global-aurora-pg), candidate hosts in regions not listed will be excluded before host selection. For non-Global Aurora dialects this parameter has no effect on this plugin.Example: us-east-1,us-west-2 |
null |
null (no restriction, all regions are accessible) |
Enabling the plugin:
properties.setProperty("wrapperPlugins","initialConnection");Configuring the plugin using the connection parameters:
properties.setProperty("openConnectionRetryTimeoutMs",40000);Configuring the plugin to disable endpoint URL substitution:
properties.setProperty("endpointSubstitutionRole", "none");
// By default the plugin will substitute reader cluster URLs with a reader instance URL, but explicitly setting this property to "none" removes this behavior.
Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:postgresql://mydb.cluster-ro-XYZ.us-east-1.rds.amazonaws.com/testdatabase", properties);Configuring the plugin to disable reader host verification when using reader cluster URLs:
properties.setProperty("verifyOpenedConnectionType", "none");
// By default the plugin will verify that we have connected to a reader when using a reader cluster URL, but explicitly setting this property to "none" removes this behavior.
Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:postgresql://mydb.cluster-ro-XYZ.us-east-1.rds.amazonaws.com/testdatabase", properties);Configuring the plugin to distribute concurrent and connection-pool prefill connections across readers:
properties.setProperty("readerInitialConnectionHostSelectorStrategy", "roundRobin");
// Wait up to 30 seconds for the cluster topology to be fetched before opening a new connection.
// This prevents concurrent connections (e.g. a connection pool prefill at startup) from all falling
// back to the DNS-resolved reader cluster endpoint and landing on a single reader. Once topology is
// available, the roundRobin strategy distributes the connections across the available readers.
properties.setProperty("waitForInitialTopologyMs", "30000");
Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:postgresql://mydb.cluster-ro-XYZ.us-east-1.rds.amazonaws.com/testdatabase", properties);