[!NOTE] 📊 We want to hear from you — community survey is open

Help us get to know who's using the AWS Advanced JDBC Wrapper. The survey is a single GitHub Discussion with one question per comment. You answer by reacting with emojis — pick all that apply, multi-select is supported.

• Takes about 3–5 minutes
• Covers usage, deployment topology, plugins, frameworks, and your experience
• Every reaction is visible to the community; total participants are counted from a single 👍 on the participation comment

👉 Take the survey

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 Advanced JDBC Wrapper 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 Advanced JDBC Wrapper is targeted to work with any existing JDBC driver. Currently, the AWS Advanced JDBC Wrapper has been validated to support the PostgreSQL JDBC Driver, MySQL JDBC Driver, and MariaDB JDBC Driver (with some caveats, see below).

The AWS Advanced JDBC Wrapper 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 Advanced JDBC Wrapper 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.

Seamless Query Caching Integration

The driver includes Remote Query Cache Plugin that stores cacheable read-only query results in a remote Valkey cache along with support for plain username/password authentication and IAM authentication with AWS ElastiCache. Applications can opt‑in per query using a SQL query hint that specifies a time‑to‑live (TTL).

Database multi-tenancy protection is disabled by default. Enable cacheEnableDatabaseMultiTenancy when query visibility depends on supported database authorization or session state. The protection covers only documented PostgreSQL and MySQL/MariaDB session state and is not a complete tenant-isolation boundary. See the Remote Query Cache Plugin for supported operations, limitations, application security requirements, and performance implications.

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 Advanced JDBC Wrapper 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 Advanced JDBC Wrapper with...

Amazon Aurora PostgreSQL and Aurora MySQL

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

Visit Using Failover 2 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 Advanced JDBC Wrapper 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 Support for RDS MultiAZ for more details.

Using the AWS Advanced JDBC Wrapper with Amazon Aurora Global Databases

As of version 3.0.0, the driver supports in-region failover and cross-region planned failover and switchover of Amazon Aurora Global Databases. A Global Writer Endpoint is also recognized and can be handled to minimize potential stale DNS issues. Please check failover plugin, failover2 plugin and Aurora Initial Connection Strategy plugin for more information.

For detailed configuration instructions, see Aurora Global Databases.

Plain Amazon RDS databases

The AWS Advanced JDBC Wrapper also provides limited functionality for RDS provided databases that are not Aurora, see the compatibility matrix for details.

RDS Proxy

As of version 3.0.0 the Simple R/W Splitting Plugin can be used with RDS Proxy. There are limitations with the AWS Advanced JDBC Wrapper 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.

The driver remains useful with RDS Proxy for authentication workflows, such as IAM authentication and AWS Secrets Manager integration. See Compatibility for compatibility information and refer to the using plugins documentation for details.

Visit Using Plain RDS for more details.

Getting Started

For more information on how to download the AWS Advanced JDBC Wrapper, 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>

Configuring the Driver with AI Tools

The driver ships with a self-contained configuration assistant skill, JDBC-WRAPPER-CONFIGURATION-ASSISTANT.md, that you can drop into your AI tool's knowledge base (Kiro, Cursor, Claude Projects, ChatGPT, Amazon Bedrock, GitHub Copilot, etc.) to help build, review, or troubleshoot wrapper configurations.

For drop-in locations, example prompts, and usage details, see Configuring the Driver with AI Tools in the Getting Started guide.

Properties

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 Advanced JDBC Wrapper.

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

Documentation

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

Using the AWS Advanced JDBC Wrapper

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

Known Limitations

MariaDB

The MariaDB driver uses pipelining for some optimizations, and Aurora does not support pipelining. MariaDB removed its own aurora failover mode in MariaDB Connector/J 3.0 for that reason. The AWS Advanced JDBC Wrapper does not use that mode, because it provides failover itself.

The wrapper's integration tests cover MariaDB Connector/J 3.5.x against Aurora MySQL. MariaDB Connector/J 3.x enables its pipelining-dependent features only when the server advertises MariaDB bulk-operation support, which Aurora MySQL does not, so those features are not used in that configuration.

To disable pipelining explicitly, use the property that matches your driver version:

• MariaDB Connector/J 3.1 and above: set disablePipeline to true.
• MariaDB Connector/J 2.x: set usePipelineAuth and useBatchMultiSend to false.

// MariaDB Connector/J 3.1 and above
Properties props = new Properties();
props.setProperty("disablePipeline", "true");

Note that usePipelineAuth and useBatchMultiSend do not exist in MariaDB Connector/J 3.x; they were removed in version 3.0. MariaDB Connector/J accepts unknown properties without raising an error, so setting them on a 3.x driver has no effect.

Amazon RDS Blue/Green Deployments

Support for Blue/Green deployments using the AWS Advanced JDBC Wrapper 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 Release 17.5, 16.9, 15.13, 14.18, 13.21 and above.
• Supported Aurora MySQL Versions: Engine Release 3.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 the Blue/Green Deployment Plugin Documentation.

Examples

Other AWS Advanced Wrapper Drivers

The AWS Advanced JDBC Wrapper is part of a broader family of AWS "wrapper" drivers that bring the same advanced functionality, such as failover support and IAM authentication, to other languages and database connectivity standards. If you are working outside of Java, you may find one of the following drivers useful:

Getting Help and Opening Issues

If you encounter a bug with the AWS Advanced JDBC Wrapper, 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:

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.