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.
| 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 |
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 |
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);