Amazon Web Services (AWS) JDBC Driver for MySQL

The Amazon Web Services (AWS) JDBC Driver for MySQL allows an application to take advantage of the features of clustered MySQL databases. It is based on and can be used as a drop-in compatible for the MySQL Connector/J driver, and is compatible with all MySQL deployments.

The AWS JDBC Driver for MySQL supports fast failover for Amazon Aurora with MySQL compatibility. Support for additional features of clustered databases, including features of Amazon RDS for MySQL and on-premises MySQL deployments, is planned.

What is Failover?

An Amazon Aurora DB cluster uses failover to automatically repairs the DB cluster status when a primary DB instance becomes unavailable. During failover, Aurora promotes a 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 for MySQL is designed to coordinate with this behavior in order to provide minimal downtime in the event of a DB instance failure.

Benefits of the AWS JDBC Driver for MySQL

Although Aurora is able to provide maximum availability through the use of failover, existing client drivers do not fully 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 for MySQL fully utilizes 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 database, 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. Additionally, as noted above, the AWS JDBC Driver is designed to be a drop-in compatible for other MySQL JDBC drivers and can be used to interact with RDS and MySQL databases as well as Aurora MySQL.

Differences between the AWS MySQL JDBC driver and the AWS JDBC Driver

The AWS JDBC Driver for MySQL is based on the open-sourced MySQL Connector/J JDBC driver and allows users to take advantage of the features of Amazon Aurora databases. The AWS JDBC driver for MySQL can be used only with MySQL databases or MySQL-compatible Amazon RDS and Amazon Aurora clusters.

The AWS JDBC Driver provides similar functionalities, but is not specific to a certain vendor database. This driver instead uses a feature layer for JDBC on top of an existing database driver that the user specifies. It was designed to work with multiple relational databases and also different drivers, whether they are community-based or proprietary drivers. The AWS JDBC Driver currently supports the MySQL and PostgreSQL databases.

Once the AWS JDBC Driver was released, it was decided new features would not be added to the AWS JDBC Driver for MySQL and that future development would be taking place in the AWS JDBC Driver project. More details can be found in the maintenance policy. The AWS JDBC Driver for MySQL is now behind in terms of features and only receives security and critical fixes. The current maintenance window for the AWS JDBC Driver for MySQL ends on July 25, 2024, and it is recommended to migrate to the AWS JDBC Driver before that date. There is a migration guide available in the AWS JDBC Driver documentation to assist users through the migration process.

For new users who are wondering which one driver to use, it is recommended to use the AWS JDBC Driver.

Getting Started

Prerequisites

You need to install Amazon Corretto 8+ or Java 8+ before using the AWS JDBC Driver for MySQL.

Installing or Upgrading the AWS JDBC Driver for MySQL

Direct Download of the .jar file

The AWS JDBC Driver for MySQL can be installed from pre-compiled packages that can be downloaded directly from GitHub Releases or Maven Central. To install the driver, obtain the corresponding JAR file and include it in the application's CLASSPATH:

Example - Direct download with wget

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1.15/aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

Upgrading to a newer version with wget

To upgrade the driver, replace the .jar file of your earlier driver with the new .jar file. After replacing the .jar file, update the CLASSPATH to include the name of the new file. For example, to upgrade to version 1.1.15:

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1.15/aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

As a Maven dependency

You can use Maven's dependency management to obtain the driver by adding the following configuration to the application's Project Object Model (POM) file:

Example - Maven

<dependencies>
  <dependency>
    <groupId>software.aws.rds</groupId>
    <artifactId>aws-mysql-jdbc</artifactId>
    <version>1.1.15</version>
  </dependency>
</dependencies>

Upgrading to a newer version with Maven

To upgrade to a newer version of the driver, replace the version number identified in the pom.xml file with the newer driver version. For example, to upgrade to version 1.1.15, modify the file to include:

<dependencies>
  <dependency>
    <groupId>software.aws.rds</groupId>
    <artifactId>aws-mysql-jdbc</artifactId>
    <version>1.1.15</version>
  </dependency>
</dependencies>

As a Gradle dependency

You can use Gradle's dependency management to obtain the driver by adding the following configuration to the application's build.gradle file:

Example - Gradle

dependencies {
    implementation group: 'software.aws.rds', name: 'aws-mysql-jdbc', version: '1.1.15'
}

Upgrading to a newer version with Gradle

To upgrade to a newer version of the driver, replace the version number identified in the application's build.gradle file with the newer driver version. For example, to upgrade to version 1.1.15:

dependencies {
    implementation group: 'software.aws.rds', name: 'aws-mysql-jdbc', version: '1.1.15'
}

Using an IDE (IntelliJ)

To use the driver with an IDE (for example, IntelliJ), download the .jar file and copy it into your libs folder. Then, add the file to your CLASSPATH:

Example - IntelliJ

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1.15/aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

After downloading the .jar file and updating the CLASSPATH, add the driver information to your Project:

1. Open Project Structure in the IntelliJ user interface.

2. Select Modules.

3. Open the Dependencies tab for your project.

4. Add the AWS JDBC Driver for MySQL .jar file.

5. Update the connection URL prefix from jdbc:mysql:// to jdbc:mysql:aws://.

Upgrading to a newer version with IntelliJ

To upgrade to a newer version of the driver, download the updated driver, and add it to your CLASSPATH:

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1.15/aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

Then, follow the steps listed above to update your project to the latest version.

Using the Driver with a database client (DBeaver)

To use the driver with the DBeaver database client, download the .jar file, copy the file to your libs folder, and add the file to your CLASSPATH:

Example - DBeaver

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1.15/aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

After downloading the .jar file and adding it to your CLASSPATH, add the driver information to the DBeaver client:

1. Open DBeaver’s Driver Manager window and click New to add the AWS JDBC Driver.

2. In Settings, enter the following information:

bash Default Port: 3306 Driver Name: AWS JDBC Driver for MySQL Class Name: software.aws.rds.jdbc.mysql.Driver URL Template: jdbc:mysql:aws://{host}:{port}

1. Go to the Libraries tab, click Add Artifact and add the following dependency declaration:

bash <dependency> <groupId>software.aws.rds</groupId> <artifactId>aws-mysql-jdbc</artifactId> </dependency>

1. DBeaver will respond: Artifacts Found: 1.

2. (Optional) To enable database selector in the UI, you can add custom queries to DBeaver. Go to the Advanced parameters and edit the following queries:

bash Get active database: select database() Set active database: use ?

1. Click OK to finish adding the driver.

After adding driver information, you can create new connections that use the AWS JDBC Driver for MySQL.

Upgrading to a newer version with the DBeaver Client

To upgrade to a newer version of the driver, download the updated driver, and add it to your CLASSPATH:

wget https://github.com/awslabs/aws-mysql-jdbc/releases/download/1.1./aws-mysql-jdbc-1.1.15.jar
cp aws-mysql-jdbc-1.1.15.jar /home/userx/libs/
export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-mysql-jdbc-1.1.15.jar

Then, follow the steps listed above to update your DBeaver client settings.

Using a Snapshot of the Driver

If there is an unreleased feature you would like to try, it may be available in a snapshot build of the driver. Snapshot builds can be found here. To use a snapshot, find the desired .jar file, which will be named aws-mysql-jdbc-<version>-<date>-<time>-<snapshot-number>.jar, and add it to your project as a dependency.

As a Maven dependency

<dependencies>
  <dependency>
    <groupId>software.aws.rds</groupId>
    <artifactId>aws-mysql-jdbc</artifactId>
    <version>1.1.16</version>
    <scope>system</scope>
    <systemPath>path-to-snapshot-jar</systemPath>
  </dependency>
</dependencies>

As a Gradle dependency

dependencies {
    implementation(files("path-to-snapshot-jar"))
}

Using the AWS JDBC Driver for MySQL

The AWS JDBC Driver for MySQL is drop-in compatible, so usage is identical to the MySQL-Connector-J JDBC driver. The sections below highlight driver usage specific to failover.

Driver Name

Use the driver name: software.aws.rds.jdbc.mysql.Driver. You'll need the driver name when loading the driver explicitly to the driver manager.

Connection URL Descriptions

There are many different types of URLs that can connect to an Aurora DB cluster; this section outlines the various URL types. For some URL types, the AWS JDBC Driver requires the user to provide some information about the Aurora DB cluster to provide failover functionality. For each URL type, information is provided below on how the driver will behave and what information the driver requires about the DB cluster, if applicable.

Note: The connection string follows standard URL parameters. In order to add parameters to the connection string, simply add ? and then the parameter_name=value pair at the end of the connection string. You may add multiple parameters by separating the parameter name and value set (parameter_name=value) with the & symbol. For example, to add 2 parameters simply add ?param_name=value&param_2=value2 at the end of the connection string.