From 365e40e39ce951c2ef7923f7bae7da379fbe684f Mon Sep 17 00:00:00 2001
From: jasonlamz <161892786+jasonlamz@users.noreply.github.com>
Date: Mon, 8 Apr 2024 11:24:32 -0700
Subject: [PATCH] docs: Aurora Initial Connection Strategy (#932)
Co-authored-by: crystall-bitquill <97126568+crystall-bitquill@users.noreply.github.com>
---
CHANGELOG.md | 4 +++
docs/Documentation.md | 1 +
.../UsingTheJdbcDriver.md | 1 +
...heAuroraInitialConnectionStrategyPlugin.md | 33 +++++++++++++++++++
4 files changed, 39 insertions(+)
create mode 100644 docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0bd913e8..50de24a9d 100644
--- 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
index 3e81aaa6c..ca3987c5d 100644
--- 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
index 58a6d51eb..094b690dc 100644
--- 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/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md
new file mode 100644
index 000000000..b32f8a3cb
--- /dev/null
+++ b/docs/using-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.
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);
+```