/aws-advanced-jdbc-wrapper

The Amazon Web Services JDBC Driver has been redesigned as an advanced JDBC wrapper. This wrapper is complementary to and extends the functionality of an existing JDBC driver to help an application take advantage of the features of clustered databases such as Amazon Aurora.

Primary LanguageJavaApache License 2.0Apache-2.0

Amazon Web Services (AWS) JDBC Driver

build_status License Maven Central Javadoc Qodana

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.

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.

In conjunction with the JDBC Drivers for PostgreSQL, MySQL, and MariaDB, the AWS JDBC Driver enables functionalities from Amazon Aurora such as fast failover for PostgreSQL and MySQL Aurora clusters. It also introduces integration with AWS authentication services such as AWS Identity and Access Management (IAM) and AWS Secrets Manager.

About the Wrapper

Hosting a database cluster in the cloud via Aurora is able to provide users with sets of features and configurations to obtain maximum performance and availability, such as database failover. However, at the moment, most existing drivers do not currently support those functionalities or are not able to entirely take advantage of it.

The main idea behind the AWS JDBC Driver is to add a software layer on top of an existing JDBC driver that would enable all the enhancements brought by Aurora, without requiring users to change their workflow with their databases and existing JDBC drivers.

What is Failover?

In an Amazon Aurora database cluster, failover is a mechanism by which Aurora automatically repairs the cluster status when a primary DB instance becomes unavailable. It achieves this goal by electing an Aurora Replica to become the new primary DB instance, so that the DB cluster can provide maximum availability to a primary read-write DB instance. The AWS JDBC Driver is designed to understand the situation and coordinate with the cluster in order to provide minimal downtime and allow connections to be very quickly restored in the event of a DB instance failure.

Benefits of the AWS JDBC Driver

Although Aurora is able to provide maximum availability through the use of failover, existing client drivers do not currently support this functionality. This is partially due to the time required for the DNS of the new primary DB instance to be fully resolved in order to properly direct the connection. The AWS JDBC Driver allows customers to continue using their existing community drivers in addition to having the AWS JDBC Driver fully exploit failover behavior by maintaining a cache of the Aurora cluster topology and each DB instance's role (Aurora Replica or primary DB instance). This topology is provided via a direct query to the Aurora DB, essentially providing a shortcut to bypass the delays caused by DNS resolution. With this knowledge, the AWS JDBC Driver can more closely monitor the Aurora DB cluster status so that a connection to the new primary DB instance can be established as fast as possible.

Enhanced Failure Monitoring

Since a database failover is usually identified by reaching a network or a connection timeout, the AWS JDBC Driver introduces an enhanced and customizable manner to faster identify a database outage.

Enhanced Failure Monitoring (EFM) is a feature available from the Host Monitoring Connection Plugin that periodically checks the connected database node's health and availability. If a database node is determined to be unhealthy, the connection is aborted (and potentially routed to another healthy node in the cluster).

Using the AWS JDBC Driver with 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.

Using the AWS JDBC Driver with plain RDS databases

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

Please visit this page for more information.

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.

Maven Central

<!-- 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
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 MonitorServiceImpl.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

This driver currently does not support switchover in Amazon RDS Blue/Green Deployments. If you do execute a Blue/Green deployment with the driver, please ensure your application is coded to retry the database connection. Retry will allow the driver to re-establish a connection to an available database instance. Without a retry, the driver would not be able to identify an available database instance, after a switchover has happened between the blue and green environments. However, please note that even with your application coded to retry the database connection, you may still encounter other unexpected errors. Support for Amazon RDS Blue/Green Deployments is in the backlog, but we cannot comment on a timeline right now.

Amazon Aurora Global Databases

This driver currently does not support failover with Amazon Aurora Global Databases. While it is possible to connect to global databases, failing over to a secondary cluster will result in errors and there may be additional unforeseen errors when working with global databases. 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 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.32
PostgreSQL 15.2
Aurora MySQL MySQL 8.0.mysql_aurora.3.02.2 (Wire-compatible with MySQL 8.0.23 onwards. For more details see here)
Aurora PostgreSQL 14.7 and 15.2 (Compatible with PostgreSQL 14.7 and 15.2, see release notes here)

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.