Skip to content

docs: clarifying blue/green compatibility with current service landscape #1512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 20, 2025
Merged

docs: clarifying blue/green compatibility with current service landscape #1512

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 17 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,25 +135,30 @@ To find all the documentation and concrete examples on how to use the AWS JDBC D

#### Amazon RDS Blue/Green Deployments

The AWS Advanced JDBC Wrapper **versions 2.6.0 and above** now include enhanced full support for Blue/Green Deployments. This support requires a minimum database version that includes a specific metadata table. This constraint **does not** apply to RDS MySQL.
**Important: Service Dependency**

**No action is required** if your database does not include the new metadata table -- the driver will continue to operate as before with no special blue/green functionality. If you have questions or encounter issues, please open an issue in this repository.
Support for Blue/Green deployments using the AWS Advanced JDBC Wrapper requires specific metadata tables that are **not available in the current RDS and Aurora service**. Please contact your AWS account team for metadata release timelines.

Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)` and above.<br>
Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21` and above.<br>
Supported Aurora MySQL Versions: Engine Release `3.07` and above.
**Limitations:**

If your database version does **not** support this table, the driver will automatically detect its absence and fallback to its previous behaviour in wrapper versions <2.6.0. In this fallback mode, Blue/Green handling is subject to the same limitations listed below.
- **Post-switchover failures:** After a Blue/Green switchover, the wrapper may not properly detect the new cluster topology, leading to failed failover attempts.
- **Metadata inconsistencies:** Discrepancies between topology metadata and actual available endpoints prevent reliable operation.
- **Version-specific issues:** Requirements vary between Aurora MySQL and Aurora PostgreSQL due to different internal systems.

AWS Advanced JDBC Wrapper **versions earlier than 2.6.0** are not compatible with [AWS Blue/Green Deployments](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html) and do not officially support them. However, the combination of the AWS Advanced JDBC Wrapper and the Failover Plugin has been validated for use with clusters that employ Blue/Green Deployments for these versions. While general basic connectivity to both Blue and Green clusters is always in place, some failover cases are not fully supported.
**If You Must Use Blue/Green (Not Recommended for Production):**

The limitations for versions earlier than 2.6.0 are:
- After a Blue/Green switchover, the wrapper may not be able to properly detect the new topology and handle failover, as there are discrepancies between the metadata and the available endpoints.
- The specific version requirements for Aurora MySQL versus Aurora PostgreSQL may vary, as the internal systems used by the wrapper can differ[^1].
1. Enable the `enableGreenNodeReplacement` configuration parameter.
2. Thoroughly test in non-production environments.

For these earlier versions, users can consider utilizing the `enableGreenNodeReplacement` configuration parameter, which allows the driver to override incorrect topology metadata and try to connect to available new Blue endpoints.
**Recommendation:**

[^1]: Aurora MySQL requires v3.07 or later.
We advise waiting for the RDS service update before enabling the Blue/Green Deployments plugin. If the metadata table does not exist, your application will continue to work; however, errors will be logged stating that relevant Blue/Green metadata cannot be found.

When the RDS service update is released, the following service versions will provide support for Blue/Green Deployments:

- Supported RDS PostgreSQL Versions: `rds_tools v1.7 (17.1, 16.5, 15.9, 14.14, 13.17, 12.21)` and above.
- Supported Aurora PostgreSQL Versions: Engine Release `17.5, 16.9, 15.13, 14.18, 13.21` and above.
- Supported Aurora MySQL Versions: Engine Release `3.07` and above.

#### Amazon Aurora Global Databases

Expand Down
11 changes: 6 additions & 5 deletions docs/Documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,18 @@
- [Database Dialects](./using-the-jdbc-driver/DatabaseDialects.md)
- [Target Driver Dialects](./using-the-jdbc-driver/TargetDriverDialects.md)
- [Plugins](./using-the-jdbc-driver/UsingTheJdbcDriver.md#plugins)
- [Aurora Connection Tracker Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
- [Aurora Initial Connection Strategy Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
- [AWS Secrets Manager Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md)
- [Blue/Green Deployment Plugin](./using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md)
- [Driver Metadata Connection Plugin](./using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md)
- [Failover Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md)
- [Failover Configuration Guide](./using-the-jdbc-driver/FailoverConfigurationGuide.md)
- [Failover Plugin v2](./using-the-jdbc-driver/using-plugins/UsingTheFailover2Plugin.md)
- [Federated Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md)
- [Host Monitoring Plugin](./using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md)
- [IAM Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md)
- [AWS Secrets Manager Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAwsSecretsManagerPlugin.md)
- [Aurora Connection Tracker Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
- [Driver Metadata Connection Plugin](./using-the-jdbc-driver/using-plugins/UsingTheDriverMetadataConnectionPlugin.md)
- [Read Write Splitting Plugin](./using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md)
- [Federated Authentication Plugin](./using-the-jdbc-driver/using-plugins/UsingTheFederatedAuthPlugin.md)
- [Aurora Initial Connection Strategy Plugin](./using-the-jdbc-driver/using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
- [Host Availability Strategy](./using-the-jdbc-driver/HostAvailabilityStrategy.md)
- [Development Guide](./development-guide/DevelopmentGuide.md)
- [Setup](./development-guide/DevelopmentGuide.md#setup)
Expand Down
7 changes: 3 additions & 4 deletions docs/using-the-jdbc-driver/using-plugins/UsingTheBlueGreenPlugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ The [Blue/Green Deployment](https://docs.aws.amazon.com/whitepapers/latest/blue-

The AWS JDBC Driver leverages the Blue/Green Deployment approach by intelligently managing traffic distribution between blue and green nodes, minimizing the impact of stale DNS data and connectivity disruptions on user applications.

**Important: Service Dependency**

Support for Blue/Green deployments using the AWS Advanced JDBC Wrapper requires specific metadata tables that are **not available in the current RDS and Aurora service**. Please contact your AWS account team for metadata release timelines.

## Prerequisites
> [!WARNING]\
Expand All @@ -21,7 +24,6 @@ The AWS JDBC Driver leverages the Blue/Green Deployment approach by intelligentl
> - AWS cluster and instance endpoints must be directly accessible from the client side
> - Connecting to database nodes using CNAME aliases is not supported
>
>
> **Blue/Green Support Behaviour and Version Compatibility:**
>
> The AWS Advanced JDBC Wrapper now includes enhanced full support for Blue/Green Deployments. This support requires a minimum database version that includes a specific metadata table. This constraint **does not** apply to RDS MySQL.
Expand All @@ -35,8 +37,6 @@ The AWS JDBC Driver leverages the Blue/Green Deployment approach by intelligentl
> Supported Aurora MySQL Versions: Engine Release `3.07` and above.




## What is Blue/Green Deployment Plugin?

During a [Blue/Green switchover](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/blue-green-deployments-switching.html), several significant changes occur to your database configuration:
Expand Down Expand Up @@ -121,4 +121,3 @@ timestamp time offset (ms) event
2025-04-23T17:42:26.536226Z 136547 ms COMPLETED
----------------------------------------------------------------------------
```