Repository files navigation

TheAmazon Web Services (AWS) JDBC Driver has been redesigned as an advanced JDBC wrapper.

The wrapper is complementary to an existing JDBC driver and aims to extend the functionality of the driver to enable applications to take full advantage of the features of clustered databases such as Amazon Aurora. In other words, the AWS JDBC Driver does not connect directly to any database, but enables support of AWS and Aurora functionalities on top of an underlying JDBC driver of the user's choice. This approach enables service-specific enhancements, without requiring users to change their workflow and existing JDBC driver tooling.

The AWS JDBC Driver is targeted to work withany existing JDBC driver. Currently, the AWS JDBC Driver has been validated to support thePostgreSQL JDBC Driver,MySQL JDBC Driver, andMariaDB JDBC Driver.

The AWS JDBC Driver provides modular functionality through feature plugins, with each plugin being relevant to specific database services based on their architecture and capabilities. For example,AWS Identity and Access Management (IAM) authentication is supported across multiple services, whileAWS Secrets Manager applies to services that support password-based authentication. The fast failover plugin provides reduced recovery time during failover for Aurora PostgreSQL and Aurora MySQL clusters.

Built-in support for AWS Identity and Access Management (IAM) authentication eliminates the need to manage database passwords, while AWS Secrets Manager integration provides secure credential management for services that require password-based authentication.

The wrapper design allows developers to continue using their preferred JDBC drivers and existing database code while gaining service-specific enhancements. No application rewrites are required.

The plugin-based design ensures applications only load the functionality they need, reducing dependencies and overhead.

For Aurora PostgreSQL, Aurora MySQL, and RDS Multi-AZ DB clusters, the driver significantly reduces connection recovery time duringdatabase failovers. By maintaining a real-time cache of cluster topology and bypassing DNS resolution delays, applications can reconnect to healthy database instances in seconds rather than minutes.

The driver includes Enhanced Failure Monitoring (EFM) that proactively monitors database node health, detecting failures faster than traditional timeout-based approaches. This allows applications to respond to issues before they impact end users.

The AWS JDBC Driver provides fast failover capabilities for Aurora PostgreSQL and Aurora MySQL clusters, significantly reducing connection recovery time during database failovers.

Visitthis page for more details.

TheAWS RDS Multi-AZ DB Clusters are capable of switching over the current writer node to another node in the cluster within approximately 1 second or less, in case of minor engine version upgrade or OS maintenance operations. The AWS JDBC Driver has been optimized for such fast failover when working with AWS RDS Multi-AZ DB Clusters.

With thefailover plugin, the downtime during certain DB cluster operations, such as engine minor version upgrades, can be reduced to one second or even less with finely tuned parameters. It supports both MySQL and PostgreSQL clusters.

Visitthis page for more details.

The AWS JDBC Driver also works with RDS provided databases that are not Aurora.

There are limitations with the AWS JDBC Driver and RDS Proxy. This is currently intended, by design, since the main reason is that RDS Proxy transparently re-routes requests to a single database instance. RDS Proxy decides which database instance is used based on many criteria (on a per-request basis). Due to this, functionality like Failover, Enhanced Host Monitoring, and Read/Write Splitting is not compatible since the driver relies on cluster topology and RDS Proxy handles this automatically.

However, the driver can still be used to handle authentication workflows. For more information regarding compatibility, please refer to the specific plugin documentation.

Visitthis page for more details.

For more information on how to download the AWS JDBC Driver, minimum requirements to use it,and how to integrate it within your project and with your JDBC driver of choice, please visit theGetting Started page.

You can find our driver by searching in The Central Repository with GroupId and ArtifactIdsoftware.amazon:aws-advanced-jdbc-wrapper.

<!-- Add the following dependency to your pom.xml,--><!-- replacing LATEST with the specific version as required--><dependency>  <groupId>software.amazon.jdbc</groupId>  <artifactId>aws-advanced-jdbc-wrapper</artifactId>  <version>LATEST</version></dependency>

A Secret ARN has the following format:arn:aws:secretsmanager:<Region>:<AccountId>:secret:SecretName-6RandomCharacters

Enabling logging is a very useful mechanism for troubleshooting any issue one might potentially experience while using the AWS JDBC Driver.

In order to learn how to enable and configure logging, check out theLogging section.

Technical documentation regarding the functionality of the AWS JDBC Driver will be maintained in this GitHub repository. Since the AWS JDBC Driver requires an underlying JDBC driver, please refer to the individual driver's documentation for driver-specific information.

To find all the documentation and concrete examples on how to use the AWS JDBC Driver, please refer to theAWS JDBC Driver Documentation page.

Support for Blue/Green deployments using the AWS Advanced JDBC Driver requires specific metadata tables. The following service versions 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 Release17.5, 16.9, 15.13, 14.18, 13.21 and above.
• Supported Aurora MySQL Versions: Engine Release3.07 and above.

Please note that Aurora Global Database and RDS Multi-AZ clusters with Blue/Green deployments is currently not supported. For detailed information on supported database versions, refer to theBlue/Green Deployment Plugin Documentation.

This driver currently does not supportplanned failover orswitchover of Amazon Aurora Global Databases. Failing over to a secondary cluster will result in errors and there may be additional unforeseen errors when working with global databases. Connecting to the primary cluster is fully supported. There is a limitation when connected to the secondary cluster; thefailover2 plugin will not work on the secondary cluster, however thefailover plugin will work. When working with Global Databases and accepting the driver's limited support, ensure you explicitly provide a list of plugins. This is crucial because thefailover2 plugin, which is enabled by default, does not support Global Databases as previously mentioned. By specifyingfailover plugin along with your desired plugins, you can ensure (still limited) functionality with Global Databases. Full Support for Amazon Aurora Global Databases is in the backlog, but we cannot comment on a timeline right now.

If you encounter a bug with the AWS JDBC Driver, we would like to hear about it.Please search theexisting issues to see if others are also experiencing the issue before reporting the problem in a new issue. GitHub issues are intended for bug reports and feature requests.

When opening a new issue, please fill in all required fields in the issue template to help expedite the investigation process.

For all other questions, please useGitHub discussions.

1. Set up your environment by following the directions in theDevelopment Guide.
2. To contribute, first make a fork of this project.
3. Make any changes on your fork. Make sure you are aware of the requirements for the project (e.g. do not require Java 7 if we are supporting Java 8 and higher).
4. Create a pull request from your fork.
5. Pull requests need to be approved and merged by maintainers into the main branch.
   Note: Before making a pull request,run all tests and verify everything is passing.

The project source code is written using theGoogle checkstyle, and the style is strictly enforced in our automation pipelines. Any contribution that does not respect/satisfy the style will automatically fail at build time.

Theaws-advanced-jdbc-wrapper has a regular monthly release cadence. A new release will occur during the last week of each month. However, if there are no changes since the latest release, then a release will not occur.

Thisaws-advanced-jdbc-wrapper is being tested against the following Community and Aurora database versions in our test suite:

Theaws-advanced-jdbc-wrapper is compatible with MySQL 5.7 and MySQL 8.0 as per the Community MySQL Connector/J 8.0 Driver.

This software is released under the Apache 2.0 license.