docs: Aurora Initial Connection Strategy (#932)

Co-authored-by: crystall-bitquill <[email protected]>
aws · Apr 8, 2024 · 365e40e · 365e40e
1 parent 27dae29
commit 365e40e
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [2.3.6] - ?
 
+### :magic_wand: Added
+- Documentation:
+  - Aurora Initial Connection Strategy Plugin. See [UsingTheAuroraInitialConnectionStrategyPlugin](https://github.com/awslabs/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
+
 ### :crab: Changed
 - Log level of `Failover.startWriterFailover` and `Failover.establishedConnection` from `fine` to `info` for better visibility of failover-related logs ([Issue #890](https://github.com/awslabs/aws-advanced-jdbc-wrapper/issues/890)).
 

diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -18,6 +18,7 @@
     - [Driver Metadata Connection Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md)
     - [Read Write Splitting Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md)
     - [Federated Authentication Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md)
+    - [Aurora Initial Connection Strategy Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
   - [Host Availability Strategy](/docs/using-the-jdbc-driver/HostAvailabilityStrategy.md)
 - [Development Guide](./development-guide/DevelopmentGuide.md)
   - [Setup](./development-guide/DevelopmentGuide.md#setup)

diff --git a/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md b/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md
@@ -178,6 +178,7 @@ The AWS JDBC Driver has several built-in plugins that are available to use. Plea
 | [Driver Metadata Connection Plugin](./using-plugins/UsingTheDriverMetadataConnectionPlugin.md)                    | `driverMetaData`          | Any database                    | Allows user application to override the return value of `DatabaseMetaData#getDriverName`                                                                                                                                                                                                                                                                                                                                                                                                                               | None                                                                                                                                                                                                          |
 | [Read Write Splitting Plugin](./using-plugins/UsingTheReadWriteSplittingPlugin.md)                                | `readWriteSplitting`      | Aurora                          | Enables read write splitting functionality where users can switch between database reader and writer instances.                                                                                                                                                                                                                                                                                                                                                                                                        | None                                                                                                                                                                                                          |
 | [Developer Plugin](./using-plugins/UsingTheDeveloperPlugin.md)                                                    | `dev`                     | Any database                    | Helps developers test various everyday scenarios including rare events like network outages and database cluster failover. The plugin allows injecting and raising an expected exception, then verifying how applications handle it.                                                                                                                                                                                                                                                                                   | None                                                                                                                                                                                                          |
+| [Aurora Initial Connection Strategy](./using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)            | `initialConnection`       | Aurora                          | Allows users to configure their initial connection strategy to reader cluster endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                               | None                                                                                                                                                                                                          |
 
 :exclamation:**NOTE**: To see information logged by plugins such as `DataCacheConnectionPlugin` and `LogQueryConnectionPlugin`,
 > see the [Logging](#logging) section.

diff --git a/...-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md b/...-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md
@@ -0,0 +1,33 @@
+# Aurora Initial Connection Strategy Plugin
+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 out of date 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 endpoint, the connected reader host will be chosen based on the configured strategy. The [initial connection strategy](../ReaderSelectionStrategies.md) 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 out of date endpoint if DNS is updating.
+
+## 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.
+
+## Aurora Initial Connection Strategy Connection Parameters
+
+The following properties can be used to configure the Aurora Initial Connection Strategy Plugin.
+
+| Parameter                                     |  Value  | Required | Description                                                                                                                                                                                                              | Example            | Default Value |
+|-----------------------------------------------|:-------:|:--------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|---------------|
+| `readerInitialConnectionHostSelectorStrategy` | String  |    No    | The strategy that will be used to select a new reader host when opening a new connection. <br><br> For more information on the available reader selection strategies, see this [table](../ReaderSelectionStrategies.md). | `leastConnections` | `random`      |
+| `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`        |
+
+## Examples
+
+Enabling the plugin:
+
+```java
+properties.setProperty("wrapperPlugins", "initialConnection");
+```
+Configuring the plugin using the connection parameters:
+
+```java
+properties.setProperty("openConnectionRetryTimeoutMs", 40000);
+```