Amazon Web Services (AWS) JDBC Driver for PostgreSQL

Note: The Amazon Web Services (AWS) JDBC Driver for PostgreSQL project has moved to a new repository. Visit us at our new repository for the latest version and information.

The Amazon Web Services (AWS) JDBC Driver for PostgreSQL allows an application to take advantage of the features of clustered PostgreSQL databases. It is based on and is drop-in compatible with the PostgreSQL JDBC Driver, and is compatible with all PostgreSQL deployments.

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

IMPORTANT Because this project is in preview, we encourage you to experiment with the PostgreSQL driver but DO NOT recommend adopting it for production use. Use of the PostgreSQL driver in preview is subject to the terms and conditions contained in the AWS Service Terms, (particularly the Beta Service Participation Service Terms) This applies to any drivers not marked as 'Generally Available'.

What is Failover?

In an Amazon Aurora DB cluster, failover is a mechanism by which Aurora automatically repairs the DB 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 for PostgreSQL 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 PostgreSQL

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 for PostgreSQL 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 PostgreSQL JDBC drivers and can be used to interact with regular RDS and PostgreSQL databases as well as Aurora PostgreSQL.

The AWS JDBC Driver Failover Process

The figure above provides a simplified overview of how the AWS JDBC Driver handles an Aurora failover encounter. Starting at the top of the diagram, an application with the AWS JDBC Driver on its class path uses the driver to get a logical connection to an Aurora database. In this example, the application requests a connection using the Aurora DB cluster endpoint and is returned a logical connection that is physically connected to the primary DB instance in the DB cluster, DB instance C. Due to how the application operates against the logical connection, the physical connection details about which specific DB instance it is connected to have been abstracted away. Over the course of the application's lifetime, it executes various statements against the logical connection. If DB instance C is stable and active, these statements succeed and the application continues as normal. If DB instance C later experiences a failure, Aurora will initiate failover to promote a new primary DB instance. At the same time, the AWS JDBC Driver will intercept the related communication exception and kick off its own internal failover process. In this case, in which the primary DB instance has failed, the driver will use its internal topology cache to temporarily connect to an active Aurora Replica. This Aurora Replica will be periodically queried for the DB cluster topology until the new primary DB instance is identified (DB instance A or B in this case). At this point, the driver will connect to the new primary DB instance and return control to the application by raising a SQLException with SQLState 08S02 so that they can reconfigure their session state as required. Although the DNS endpoint for the DB cluster might not yet resolve to the new primary DB instance, the driver has already discovered this new DB instance during its failover process and will be directly connected to it when the application continues executing statements. In this way the driver provides a faster way to reconnect to a newly promoted DB instance, thus increasing the availability of the DB cluster.

Getting Started

Minimum Requirements

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

Obtaining the AWS JDBC Driver for PostgreSQL

Direct Download

The AWS JDBC Driver for PostgreSQL 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 via wget

wget https://github.com/awslabs/aws-postgresql-jdbc/releases/download/0.2.0/aws-postgresql-jdbc-0.2.0.jar

Example - Adding the Driver to the CLASSPATH

export CLASSPATH=$CLASSPATH:/home/userx/libs/aws-postgresql-jdbc-0.2.0.jar

As a Maven Dependency

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

Example - Maven

<dependencies>
  <dependency>
    <groupId>software.aws.rds</groupId>
    <artifactId>aws-postgresql-jdbc</artifactId>
    <version>0.1.0</version>
  </dependency>
</dependencies>

As a Gradle Dependency

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

Example - Gradle

dependencies {
    compile group: 'software.aws.rds', name: 'aws-postgresql-jdbc', version: '0.1.0'
}

Using the AWS JDBC Driver for PostgreSQL

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

Driver Name

Use the driver name: software.aws.rds.jdbc.postgresql.Driver. You will need this name when loading the driver explicitly to the driver manager.

Driver Protocol

Currently, the driver only supports the following protocol for the connection string: jdbc:postgresql:aws:. The driver does not support any other protocols to avoid potential conflicts with other PostgreSQL JDBC drivers.

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 about 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. To add parameters to the connection string, simply add ? and then the parameter_name=value pair at the end of the connection string. You can add multiple parameters by separating the parameter name and value pair (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.

URL Type	Example	Required Parameters	Driver Behavior
Cluster Endpoint	jdbc:postgresql:aws://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:5432	None	Initial connection: primary DB instanceFailover behavior: connect to the new primary DB instance
Read-Only Cluster Endpoint	jdbc:postgresql:aws://db-identifier.cluster-ro-XYZ.us-east-2.rds.amazonaws.com:5432	None	Initial connection: any Aurora ReplicaFailover behavior: prioritize connecting to any active Aurora Replica but might connect to the primary DB instance if it provides a faster connection
Instance Endpoint	jdbc:postgresql:aws://instance-1.XYZ.us-east-2.rds.amazonaws.com:5432	None	Initial connection: the instance specified (DB instance 1)Failover behavior: connect to the primary DB instance
RDS Custom Cluster	jdbc:postgresql:aws://db-identifier.cluster-custom-XYZ.us-east-2l.rds.amazonaws.com:5432	None	Initial connection: any DB instance in the custom DB clusterFailover behavior: connect to the primary DB instance (note that this might be outside of the custom DB cluster)
IP Address	jdbc:postgresql:aws://10.10.10.10:5432	clusterInstanceHostPattern	Initial connection: the DB instance specifiedFailover behavior: connect to the primary DB instance
Custom Domain	jdbc:postgresql:aws://my-custom-domain.com:5432	clusterInstanceHostPattern	Initial connection: the DB instance specifiedFailover behavior: connect to the primary DB instance
Non-Aurora Endpoint	jdbc:postgresql:aws://localhost:5432

Information about the clusterInstanceHostPattern is provided in the section below.

For more information about parameters that can be configured with the AWS JDBC Driver, see the section below about failover parameters.

Failover Parameters

In addition to the parameters that you can configure for the PostgreSQL JDBC Driver, you can pass the following parameters to the AWS JDBC Driver through the connection URL to specify additional driver behavior.

Parameter	Value	Required	Description
enableClusterAwareFailover	Boolean	No	Set to true to enable the fast failover behavior offerred by the AWS JDBC Driver. Set to false for simple JDBC connections that do not require fast failover functionality.Default value: true
clusterInstanceHostPattern	String	If connecting using an IP address or custom domain URL: YesOtherwise: No	This para