Aurora Global Databases

Since version: 3.0.0

The AWS Advanced JDBC Wrapper provides comprehensive support for Amazon Aurora Global Databases, including both in-region and cross-region failover capabilities.

Overview

Aurora Global Database is a feature that allows a single Aurora database to span multiple AWS regions. It provides fast replication across regions with minimal impact on database performance, enabling disaster recovery and serving read traffic from multiple regions.

The AWS Advanced JDBC Wrapper supports:

• In-region failover
• Cross-region planned failover and switchover
• Global Writer Endpoint recognition
• Stale DNS handling

Configuration

The following instructions are recommended by AWS Service Teams for Aurora Global Database connections. This configuration provides writer connections with support for both in-region and cross-region failover.

Writer Connections

Connection String: Use the global cluster endpoint:

<global-db-name>.global-<XYZ>.global.rds.amazonaws.com

Configuration Parameters:

Parameter	Value	Notes
clusterId	1	See clusterId parameter documentation
wrapperDialect	global-aurora-mysql or global-aurora-pg
wrapperPlugins	initialConnection,failover2,efm2 or initialConnection,gdbFailover,efm2	Without connection pooling
	auroraConnectionTracker,initialConnection,failover2,efm2 or auroraConnectionTracker,initialConnection,gdbFailover,efm2	With connection pooling
globalClusterInstanceHostPatterns	?.XYZ1.us-east-2.rds.amazonaws.com,?.XYZ2.us-west-2.rds.amazonaws.com	See documentation

Note: Add additional plugins according to the compatibility guide.

Reader Connections

Connection String: Use the cluster reader endpoint:

<cluster-name>.cluster-ro-<XYZ>.<region>.rds.amazonaws.com

Configuration Parameters:

Parameter	Value	Notes
clusterId	1	Use the same value as writer connections
wrapperDialect	global-aurora-mysql or global-aurora-pg
wrapperPlugins	initialConnection,failover2,efm2 or initialConnection,gdbFailover,efm2	Without connection pooling
	auroraConnectionTracker,initialConnection,failover2,efm2 or auroraConnectionTracker,initialConnection,gdbFailover,efm2	With connection pooling
globalClusterInstanceHostPatterns	Same as writer configuration
failoverMode	strict-reader or reader-or-writer	Depending on system requirements

Note: Add additional plugins according to the compatibility guide.

Example Configuration

Java Code Example

import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

public class GlobalDatabaseExample {
    public static void main(String[] args) throws Exception {
        // Writer connection
        String writerUrl = "jdbc:aws-wrapper:mysql://my-global-db.global-xyz.global.rds.amazonaws.com:3306/mydb";
        Properties writerProps = new Properties();
        writerProps.setProperty("user", "username");
        writerProps.setProperty("password", "password");
        writerProps.setProperty("clusterId", "1");
        writerProps.setProperty("wrapperDialect", "global-aurora-mysql");
        writerProps.setProperty("wrapperPlugins", "initialConnection,failover2,efm2");
        writerProps.setProperty("globalClusterInstanceHostPatterns", 
            "?.abc123.us-east-1.rds.amazonaws.com,?.def456.us-west-2.rds.amazonaws.com");
        
        Connection writerConn = DriverManager.getConnection(writerUrl, writerProps);
        
        // Reader connection
        String readerUrl = "jdbc:aws-wrapper:mysql://my-cluster.cluster-ro-xyz.us-east-1.rds.amazonaws.com:3306/mydb";
        Properties readerProps = new Properties();
        readerProps.setProperty("user", "username");
        readerProps.setProperty("password", "password");
        readerProps.setProperty("clusterId", "1");
        readerProps.setProperty("wrapperDialect", "global-aurora-mysql");
        readerProps.setProperty("wrapperPlugins", "initialConnection,failover2,efm2");
        readerProps.setProperty("globalClusterInstanceHostPatterns", 
            "?.abc123.us-east-1.rds.amazonaws.com,?.def456.us-west-2.rds.amazonaws.com");
        readerProps.setProperty("failoverMode", "strict-reader");
        
        Connection readerConn = DriverManager.getConnection(readerUrl, readerProps);
    }
}

Important Considerations

Database instance names

Plugin Selection

• Connection Pooling: Include auroraConnectionTracker plugin when using connection pooling
• gdbFailover plugin has extended failover functionality and supports application home region

Global Cluster Instance Host Patterns

The globalClusterInstanceHostPatterns parameter is required for Aurora Global Databases. The patterns are based on instance endpoints. It should contain:

• Comma-separated list of host patterns for each region
• Different cluster identifiers for each region (e.g., XYZ1, XYZ2)
• Proper region specification for custom domains: [us-east-1]?.custom.com

Failover Behavior

• In-region failover: Automatic failover within the same region
• Cross-region failover: Planned failover to a different region
• DNS handling: The initialConnection plugin helps mitigate stale DNS issues

Restricting Access to Specific Regions

If your application can only reach a subset of the regions a Global Database spans (due to network reachability, compliance, or latency constraints), use the gdbAccessibleRegions property to restrict the wrapper to those regions. See Restricting Aurora Global Database Access by Region for details.

Monitoring Connection Priority

The topology monitor's background connection can be directed to a preferred node type or region using gdbMonitoringConnectionPriority. See Monitoring Connection Priority for details.

Compatibility

For detailed compatibility information, see:

• Database Types Compatibility
• Endpoint Types Compatibility
• Cross-Plugin Compatibility

Related Documentation

• Failover Plugin v2
• Aurora Initial Connection Strategy Plugin
• Restricting Aurora Global Database Access by Region
• Monitoring Connection Priority
• IAM Authentication Plugin
• Database Dialects