Amazon Web Services (AWS) JDBC Driver

The Amazon 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 with any existing JDBC driver. Currently, the AWS JDBC Driver has been validated to support the PostgreSQL JDBC Driver, MySQL JDBC Driver, and MariaDB 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, while AWS 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.

Benefits of the AWS JDBC Driver for All Aurora and RDS Database Services

Seamless AWS Authentication Service Integration

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.

Preserve Existing Workflows

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.

Modular Plugin Architecture

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

Benefits of the AWS JDBC Driver for Aurora PostgreSQL, Aurora MySQL, and RDS

Faster Failover and Reduced Downtime

For Aurora PostgreSQL, Aurora MySQL, and RDS Multi-AZ DB clusters, the driver significantly reduces connection recovery time during database 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.

Enhanced Failure Detection

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.

Using the AWS JDBC Driver with...

Amazon Aurora PostgreSQL and Aurora MySQL

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

Visit this page for more details.

Amazon RDS Multi-AZ DB Clusters

The AWS 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 the failover 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.

Visit this page for more details.

Plain Amazon RDS databases

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

Visit this page for more details.

Getting Started

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 the Getting Started page.

Maven Central

You can find our driver by searching in The Central Repository with GroupId and ArtifactId software.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>

Properties

Parameter	Reference	Documentation Link
wrapperDialect	DialectManager.DIALECT	Dialects, and whether you should include it.
wrapperPlugins	PropertyDefinition.PLUGINS
secretsManagerSecretId	AwsSecretsManagerConnectionPlugin.SECRET_ID_PROPERTY	SecretsManagerPlugin
secretsManagerRegion	AwsSecretsManagerConnectionPlugin.REGION_PROPERTY	SecretsManagerPlugin
wrapperDriverName	DriverMetaDataConnectionPlugin.WRAPPER_DRIVER_NAME	DriverMetaDataConnectionPlugin
failoverMode	FailoverConnectionPlugin.FAILOVER_MODE	FailoverPlugin
clusterInstanceHostPattern	AuroraHostListProvider.CLUSTER_INSTANCE_HOST_PATTERN	FailoverPlugin
enableClusterAwareFailover	FailoverConnectionPlugin.ENABLE_CLUSTER_AWARE_FAILOVER	FailoverPlugin
failoverClusterTopologyRefreshRateMs	FailoverConnectionPlugin.FAILOVER_CLUSTER_TOPOLOGY_REFRESH_RATE_MS	FailoverPlugin
failoverReaderConnectTimeoutMs	FailoverConnectionPlugin.FAILOVER_READER_CONNECT_TIMEOUT_MS	FailoverPlugin
failoverTimeoutMs	FailoverConnectionPlugin.FAILOVER_TIMEOUT_MS	FailoverPlugin
failoverWriterReconnectIntervalMs	FailoverConnectionPlugin.FAILOVER_WRITER_RECONNECT_INTERVAL_MS	FailoverPlugin
clusterTopologyHighRefreshRateMs	MonitoringRdsHostListProvider.CLUSTER_TOPOLOGY_HIGH_REFRESH_RATE_MS	FailoverPlugin v2
failoverReaderHostSelectorStrategy	software.amazon.jdbc.plugin.failover2. FailoverConnectionPlugin.FAILOVER_READER_HOST_SELECTOR_STRATEGY	FailoverPlugin v2
failureDetectionCount	HostMonitoringConnectionPlugin.FAILURE_DETECTION_COUNT	HostMonitoringPlugin
failureDetectionEnabled	HostMonitoringConnectionPlugin.FAILURE_DETECTION_ENABLED	HostMonitoringPlugin
failureDetectionInterval	HostMonitoringConnectionPlugin.FAILURE_DETECTION_INTERVAL	HostMonitoringPlugin
failureDetectionTime	HostMonitoringConnectionPlugin.FAILURE_DETECTION_TIME	HostMonitoringPlugin
monitorDisposalTime	HostMonitorServiceImpl.MONITOR_DISPOSAL_TIME_MS	HostMonitoringPlugin
iamDefaultPort	IamAuthConnectionPlugin.IAM_DEFAULT_PORT	IamAuthenticationPlugin
iamHost	IamAuthConnectionPlugin.IAM_HOST	IamAuthenticationPlugin
iamRegion	IamAuthConnectionPlugin.IAM_REGION	IamAuthenticationPlugin
iamExpiration	IamAuthConnectionPlugin.IAM_EXPIRATION	IamAuthenticationPlugin
awsProfile	PropertyDefinition.AWS_PROFILE	AWS Advanced JDBC Driver Parameters
wrapperLogUnclosedConnections	PropertyDefinition.LOG_UNCLOSED_CONNECTIONS	AWS Advanced JDBC Driver Parameters
wrapperLoggerLevel	PropertyDefinition.LOGGER_LEVEL	Logging
wrapperProfileName	PropertyDefinition.PROFILE_NAME	Configuration Profiles
autoSortWrapperPluginOrder	PropertyDefinition.AUTO_SORT_PLUGIN_ORDER	Plugins
loginTimeout	PropertyDefinition.LOGIN_TIMEOUT	AWS Advanced JDBC Driver Parameters
connectTimeout	PropertyDefinition.CONNECT_TIMEOUT	AWS Advanced JDBC Driver Parameters
socketTimeout	PropertyDefinition.SOCKET_TIMEOUT	AWS Advanced JDBC Driver Parameters
tcpKeepAlive	PropertyDefinition.TCP_KEEP_ALIVE	AWS Advanced JDBC Driver Parameters

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

Logging

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 the Logging section.

Documentation

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.

Using the AWS JDBC Driver

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

Known Limitations

Amazon RDS Blue/Green Deployments

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.

Limitations:

• 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.

If You Must Use Blue/Green (Not Recommended for Production):

1. Enable the enableGreenNodeReplacement configuration parameter.
2. Thoroughly test in non-production environments.

Recommendation:

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

This driver currently does not support planned failover or switchover 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; the failover2 plugin will not work on the secondary cluster, however the failover 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 the failover2 plugin, which is enabled by default, does not support Global Databases as previously mentioned. By specifying failover 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.

Examples

Description	Examples
Using the AWS JDBC Driver to get a simple connection	PostgreSQL
Using the AWS JDBC Driver with failover handling	PostgreSQL
Using the AWS IAM Authentication Plugin with DriverManager	PostgreSQL MySQL MariaDB
Using the AWS IAM Authentication Plugin with DataSource	PostgreSQL and MySQL
Using the AWS Secrets Manager Plugin with DriverManager	PostgreSQL MySQL
Using the AWS Credentials Manager to configure an alternative AWS credentials provider.	PostgreSQL and MySQL
Using the AWS JDBC Driver with AWSWrapperDatasource	PostgreSQL
Using the Driver Metadata Plugin to override driver name, this plugin enables specific database features that may only be available to target drivers	PostgreSQL
Using the Read/Write Splitting Plugin with DriverManager	PostgreSQL MySQL
Using the Read/Write Splitting Plugin with Spring	PostgreSQL MySQL
Using HikariCP with the AWSWrapperDatasource	PostgreSQL
Using HikariCP with the AWSWrapperDatasource with failover handling	PostgreSQL
Using Spring and HikariCP with the AWS JDBC Driver	PostgreSQL
Using Spring and HikariCP with the AWS JDBC Driver and failover handling	PostgreSQL
Using Spring and Hibernate with the AWS JDBC Driver	PostgreSQL
Using Spring and Wildfly with the AWS JDBC Driver	PostgreSQL
Using Vert.x and c3p0 with the AWS JDBC Driver	PostgreSQL
Using the AWS JDBC Driver with Telemetry and using the AWS Distro for OpenTelemetry Collector	PostgreSQL
Using the AWS JDBC Driver with Telemetry and using the AWS X-Ray Daemon	PostgreSQL

Getting Help and Opening Issues

If you encounter a bug with the AWS JDBC Driver, we would like to hear about it. Please search the existing 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 use GitHub discussions.

How to Contribute

1. Set up your environment by following the directions in the Development 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.

Code Style

The project source code is written using the Google 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.

Releases

The aws-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.

Aurora Engine Version Testing

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

Database	Versions
MySQL	8.0.36
PostgreSQL	16.2
Aurora MySQL	- Default version. To check the default version, open the RDS "Create database" page in the AWS console and check the pre-selected database version. - Latest release, as shown on this page.
Aurora PostgreSQL	- Default version. To check the default version, open the RDS "Create database" page in the AWS console and check the pre-selected database version. - Latest release, as shown on this page.

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

License

This software is released under the Apache 2.0 license.