docs: compatibility guide (#1567)

sergiyvamz · web-flow · commit 139a57dc4e1e · 2025-10-20T15:12:01.000-07:00
diff --git a/docs/using-the-jdbc-driver/Compatibility.md b/docs/using-the-jdbc-driver/Compatibility.md
@@ -0,0 +1,16 @@
+# Plugins compatibility
+
+The AWS JDBC Driver uses plugins to execute JDBC methods. You can think of a plugin as an extensible code module that adds additional logic around JDBC method calls. Plugins are designed with the intention of being compatible with each other; however, there are logical constraints related to database type or database features that can make plugins inefficient in certain configurations.
+
+For example, RDS Single-AZ Instance deployments do not support failover, so the `failover` and `failover2` plugins are marked as incompatible. If either of these plugins is included in the driver configuration, there will be no added value. However, these unnecessary plugins will function without errors and will simply consume additional resources.
+
+The following matrices help verify plugin compatibility with other plugins and with various database types. Some plugins are sensitive to the database URL provided in the connection string, and this is also presented below.
+
+We encourage users to verify their configurations and ensure that their configuration contains no incompatible components.
+
+- [Database type compatibility](./CompatibilityDatabaseTypes.md)
+- [Database URL type compatibility](./CompatibilityEndpoints.md)
+- [Cross Plugins compatibility](./CompatibilityCrossPlugins.md)
+
+
+
diff --git a/docs/using-the-jdbc-driver/CompatibilityCrossPlugins.md b/docs/using-the-jdbc-driver/CompatibilityCrossPlugins.md
diff --git a/docs/using-the-jdbc-driver/CompatibilityDatabaseTypes.md b/docs/using-the-jdbc-driver/CompatibilityDatabaseTypes.md
diff --git a/docs/using-the-jdbc-driver/CompatibilityEndpoints.md b/docs/using-the-jdbc-driver/CompatibilityEndpoints.md
diff --git a/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md b/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md
@@ -225,6 +225,8 @@ The AWS JDBC Driver has several built-in plugins that are available to use. Plea
 In addition to the built-in plugins, you can also create custom plugins more suitable for your needs.
 For more information, see [Custom Plugins](../development-guide/LoadablePlugins.md#using-custom-plugins).
 
+Some plugins, database types and database URL types may be incompatible. For more information see the [compatibility guide](./Compatibility.md).
+
 ### Using a Snapshot of the Driver
 If there is an unreleased feature you would like to try, it may be available in a snapshot build of the driver.
 To use a snapshot build in your project, check the following examples. More information available within this [documentation](https://central.sonatype.org/publish/publish-portal-snapshots/#publishing-via-other-methods).
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md
@@ -3,6 +3,8 @@
 This plugin tracks all the opened connections. In the event of a cluster failover, this plugin will close all the impacted connections.
 If no plugins are explicitly specified, this plugin is enabled by default.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## Use Case
 User applications can have two types of connections:
 
@@ -15,3 +17,4 @@ When the application tries to continue the workflow with the idle connection tha
 
 Since the Aurora Connection Tracker Plugin keeps track of all the open connections, the plugin can close all impacted connections after failover.
 When the application tries to use the outdated idle connection, the application will get a `connection's closed` error instead.
+
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md
@@ -5,6 +5,8 @@ When this plugin is enabled, if the initial connection is to a reader cluster en
 
 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.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## 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.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md
@@ -9,6 +9,8 @@ To enable the AWS Secrets Manager Connection Plugin, add the plugin code `awsSec
 
 This plugin requires valid AWS credentials. See more details at [AWS Credentials Configuration](../custom-configuration/AwsCredentialsConfiguration.md)
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## AWS Secrets Manager Connection Plugin Parameters
 The following properties are required for the AWS Secrets Manager Connection Plugin to retrieve database credentials from the AWS Secrets Manager.
 
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md
@@ -59,6 +59,7 @@ All factors mentioned above may cause application disruption. The AWS Advanced J
 - Automatically rejects new connection requests to green nodes when the switchover is completed but DNS entries for green nodes remain temporarily available
 - Intelligently detects switchover failures and rollbacks to the original state, implementing appropriate connection handling measures to maintain application stability
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
 
 ## How do I use Blue/Green Deployment Plugin with the AWS JDBC Driver?
 
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheCustomEndpointPlugin.md
@@ -2,6 +2,8 @@
 
 The Custom Endpoint Plugin adds support for RDS custom endpoints. When the Custom Endpoint Plugin is in use, the driver will analyse custom endpoint information to ensure instances used in connections are part of the custom endpoint being used. This includes connections used in failover and read-write splitting.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## Prerequisites
 - This plugin requires the following runtime dependencies to be registered separately in the classpath:
     - [AWS Java SDK RDS v2.7.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds)
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheDeveloperPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheDeveloperPlugin.md
@@ -8,6 +8,8 @@ Since some exceptions raised by the drivers rarely happen, testing for those mig
 
 The `dev` plugin code should be added to the connection plugins parameter in order to be able to intercept JDBC calls and raise a test exception when conditions are met.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ### Simulate an exception while opening a new connection
 
 The plugin introduces a new class `ExceptionSimulationManager` that will handle how a given exception will be passed to the connection to be tested.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md
@@ -6,15 +6,17 @@ In some cases, user application may require the underlying driver's name for som
 For instance, Hibernate ORM explicitly checks for the driver name to enable native handling for advanced PostgreSQL data types.
 The Driver Metadata Connection Plugin allows user application to override the wrapper's name to address these scenarios.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## Enabling the Driver Metadata Connection Plugin
 
 To enable the Driver Metadata Connection Plugin, add the plugin code `driverMetaData` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value, or to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters).
 
 ## Driver Metadata Connection Plugin Parameters
 
-| Parameter                | Value  | Required | Description                                             | Example            | Default Value |
-|--------------------------|:------:|:--------:|:--------------------------------------------------------|:-------------------|---------------|
-| `wrapperDriverName` | String |   Yes    | Override this value to return a specific driver name for the DatabaseMetaData#getDriverName method. | `CustomDriverName` | `Amazon Web Services (AWS) Advanced JDBC Wrapper`        |
+| Parameter           | Value  | Required | Description                                                                                         | Example            | Default Value                                     |
+|---------------------|:------:|:--------:|:----------------------------------------------------------------------------------------------------|:-------------------|---------------------------------------------------|
+| `wrapperDriverName` | String |   Yes    | Override this value to return a specific driver name for the DatabaseMetaData#getDriverName method. | `CustomDriverName` | `Amazon Web Services (AWS) Advanced JDBC Wrapper` |
 
 ### Example
 [DriverMetaDataConnectionPluginExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/DriverMetaDataConnectionPluginExample.java)
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md
@@ -50,6 +50,7 @@ Please refer to the [failover configuration guide](../FailoverConfigurationGuide
 > [!WARNING]
 > Do not use the `failover` and `failover2` plugins at the same time for the same connection! 
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
 
 ### Failover Plugin v2 Configuration Parameters
 In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters for the AWS JDBC Driver through the connection URL to specify additional failover behavior.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md
@@ -18,6 +18,8 @@ At this point, the JDBC Driver will connect to the new primary DB instance and r
 ## Using the Failover Plugin
 The Failover Plugin v1 will **NOT** be enabled by default. Instead, the newer [Failover Plugin v2](./UsingTheFailover2Plugin.md) will be enabled by default if the [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) value is not specified. If you would like to use the Failover Plugin v1 instead of v2, it must be explicitly included by adding the plugin code `failover` to the [`wrapperPlugins`](../UsingTheJdbcDriver.md#aws-advanced-jdbc-driver-parameters) value, or by adding it to the current [driver profile](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters). After you load the plugin, the failover feature will be enabled by default and the enableClusterAwareFailover parameter will be set to true. <br> <br> Please refer to the [failover configuration guide](../FailoverConfigurationGuide.md) for tips to keep in mind when using the failover plugin.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ### Failover Parameters
 In addition to the parameters that you can configure for the underlying driver, you can pass the following parameters to the AWS JDBC Driver through the connection URL to specify additional failover behavior.
 
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md
@@ -24,6 +24,8 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates
 >
 > It's recommended to use [AWS Java SDK RDS v2.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds) when it's possible.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ### Bundled Uber JAR
 Included in AWS JDBC Driver release, is an Uber JAR that bundles the AWS JDBC Driver and all the package dependencies needed to use the Federated Authentication Plugin. 
 It is suffixed with `-bundle-federated-auth`.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md
@@ -90,3 +90,4 @@ The `efm2` plugin is designed to address [some of the issues](https://github.com
 - Reviewed and redesigned stopping of idle monitoring threads
 - Reviewed and simplified monitoring logic
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md
@@ -20,6 +20,8 @@ To enable the IAM Authentication Connection Plugin, add the plugin code `iam` to
 
 This plugin requires valid AWS credentials. See more details at [AWS Credentials Configuration](../custom-configuration/AwsCredentialsConfiguration.md)
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## AWS IAM Database Authentication
 The AWS JDBC Driver supports Amazon AWS Identity and Access Management (IAM) authentication. When using AWS IAM database authentication, the host URL must be a valid Amazon endpoint, and not a custom domain or an IP address.
 <br>ie. `db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheLimitlessConnectionPlugin.md
@@ -40,6 +40,8 @@ The Limitless Connection Plugin is compatible with authentication type plugins s
 However, we don't recommend using them with the Limitless Connection Plugin because they're not designed to be used with Aurora Limitless Database. 
 They don't provide any extra value, and add unnecessary computation and memory overhead.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ### Use with Connection Pools
 Connection pools keep connections open for reuse, but this can work against the client-side load-balancing of the Limitless Connection Plugin and cause an imbalanced load on transaction routers.
 To mitigate this, consider setting connection properties that can reduce the number of idle connections or increase the lifetime of connections.
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheOktaAuthPlugin.md
@@ -25,6 +25,8 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates
 >
 > It's recommended to use [AWS Java SDK RDS v2.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds) when it's possible.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ## How to use the Okta Authentication Plugin with the AWS JDBC Driver 
 
 ### Enabling the Okta Authentication Plugin
diff --git a/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md b/docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md
@@ -94,6 +94,8 @@ props.setProperty(ReadWriteSplittingPlugin.READER_HOST_SELECTOR_STRATEGY.name, "
 
 When a Statement or ResultSet is created, it is internally bound to the database connection established at that moment. There is no standard JDBC functionality to change the internal connection used by Statement or ResultSet objects. Consequently, even if the read/write plugin switches the internal connection, any Statements/ResultSets created before this will continue using the old database connection. This bypasses the desired functionality provided by the plugin. To prevent these scenarios, an exception will be thrown if your code uses any Statements/ResultSets created before a change in internal connection. To solve this problem, please ensure you create new Statement/ResultSet objects after switching between the writer/reader.
 
+Verify plugin compatibility within your driver configuration using the [compatibility guide](../Compatibility.md).
+
 ### Session state
 
 The plugin supports session state transfer when switching connection. All attributes mentioned in [Session State](../SessionState.md) are automatically transferred to a new connection. 
