Skip to content

GlobalDatabases.md

Latest commit

 

History

History
146 lines (110 loc) · 9.2 KB

GlobalDatabases.md

File metadata and controls

146 lines (110 loc) · 9.2 KB
Raw

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

Warning

The plugin does not support duplicate instance names across regions. Ensure that all instance names are unique across all GDB regions.

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:

Related Documentation