DOCSEARCHbyAlgolia
Submit Docs

AWS Advanced JDBC Wrapper

repository·main·Indexed 43 days ago

https://github.com/aws/aws-advanced-jdbc-wrapper

A modular enhancement layer for JDBC drivers that provides AWS-specific features including fast failover for Aurora, IAM authentication, remote query caching, and column-level encryption via AWS KMS. It integrates with Spring Boot, HikariCP, and Hibernate, allowing developers to add advanced capabilities without replacing their underlying database drivers.

Tokens
193K
Snippets
316
Records
575
Agent score
53%

What's inside AWS Advanced JDBC Wrapper

  1. Overview of AWS Advanced JDBC Wrapper testing types

    main

    The project uses several testing layers to ensure correctness and performance across JVM and GraalVM:

    • Unit tests: Verifies the core correctness of the wrapper.
    • Failover integration tests: Tests reader and writer failover workflows using the Failover Connection Plugin.
    • Enhanced failure monitoring integration tests: Tests failure detection using the Host Monitoring Connection Plugin.
    • AWS authentication integration tests: Tests authentication methods via AWS Secrets Manager Plugin or AWS IAM Authentication Plugin.
    • Connection plugin manager benchmarks: Measures the overhead of executing JDBC method calls with multiple plugins enabled.

  2. What is Host Availability Strategy

    main

    The AWS Advanced JDBC Wrapper tracks the availability status of database hosts as either AVAILABLE or NOT_AVAILABLE. When a host fails, it is marked as NOT_AVAILABLE and the driver will stop attempting to connect to it.

    Host Availability Strategies are mechanisms used to refresh these statuses. They allow the driver to periodically check if a previously NOT_AVAILABLE host has recovered and become AVAILABLE again. This prevents the driver from permanently ignoring hosts that have recovered from a transient failure.

  3. What is the AWS Advanced JDBC Wrapper?

    main

    The AWS Advanced JDBC Wrapper is a complementary layer that sits on top of an existing JDBC driver. It does not connect directly to a database; instead, it extends the functionality of your chosen underlying driver to enable advanced features for AWS database services like Amazon Aurora and Amazon RDS.

    Key Characteristics:

    • Complementary: Works with your existing JDBC driver (e.g., PostgreSQL, MySQL, or MariaDB drivers).
    • Modular: Uses a plugin-based architecture so you only load the functionality you need.
    • Non-Breaking: Designed to preserve existing workflows without requiring application rewrites.

  4. What is a session state in the AWS Advanced JDBC Wrapper?

    main

    A session state is a collection of related session settings associated with a database connection. The AWS Advanced JDBC Wrapper tracks these settings to ensure that when a physical connection is switched (e.g., during a cluster failover), the new connection maintains the same configuration as the previous one.

    The following session settings are tracked:

    • autoCommit (setAutoCommit, getAutoCommit)
    • readOnly (isReadOnly, setReadOnly)
    • transaction isolation level (setTransactionIsolation, getTransactionIsolation)
    • holdability (setHoldability, getHoldability)
    • networkTimeout (setNetworkTimeout, getNetworkTimeout)
    • catalog (setCatalog, getCatalog)
    • schema (setSchema, getSchema)
    • typesMapping (setTypeMap, getTypeMap)

  5. Overview of the KMS Encryption Plugin

    main

    The KMS Encryption Plugin provides transparent column-level encryption using AWS Key Management Service (KMS). It implements envelope encryption where AWS KMS manages master keys that encrypt data keys, which in turn encrypt your actual data.

    Key Features:

    • Transparent Operation: Encryption and decryption occur automatically via JDBC through PreparedStatement and ResultSet.
    • Automatic Detection: The plugin parses SQL to detect columns marked for encryption.
    • Integrity Verification: Uses HMAC-based verification to ensure data has not been tampered with.
    • Supported Databases: PostgreSQL (12+) and MySQL (8.0+).
    • Manual Control: Supports manual annotation for explicit column specification.

  6. How the Simple Read/Write Splitting Plugin verifies connections

    main

    When verifyNewSrwConnections is enabled (default), the plugin executes a role-verification query on every new connection to ensure it is connected to the correct host type (writer vs. reader). If verification fails, the plugin retries based on srwConnectRetryTimeoutMs and srwConnectRetryIntervalMs.

    Role Verification Queries by Database Type:

    • PostgreSQL: SELECT pg_catalog.pg_is_in_recovery()
    • Aurora MySQL: SELECT @@innodb_read_only
    • MySQL, MariaDB: SELECT @@read_only

    Important: Autocommit and Verification Errors If autocommit is set to false, calling setReadOnly may trigger a verification query that opens a new transaction. This can result in the error: Cannot change transaction read-only property in the middle of a transaction.

    To avoid this, either:

    1. Ensure the plugin has already connected to the target connection before setting autocommit to false.
    2. Disable verification by setting verifyNewSrwConnections to false.

  7. Configure nested tracing strategies using Amazon XRay

    main

    The AWS Advanced JDBC Wrapper supports hierarchical tracing. When using Telemetry, you can decide whether driver-generated traces should be submitted as independent top-level traces or nested within existing application traces.

    • Top-level trace: A trace with no parent, directly accessible in AWS X-Ray.
    • Nested trace: A trace hierarchically linked to a parent trace (e.g., individual plugin traces linked to a parent JDBC call trace).

    If your application already has open telemetry traces, you can control the relationship between application traces and driver traces using the telemetrySubmitToplevel property.

    # Example configuration logic:
# Set to true to attempt top-level submission
# Set to false (default) to nest within application traces
telemetrySubmitToplevel=false

  9. Understanding Host List Providers

    main

    Host List Providers are used by the Plugin Service to retrieve database topology or host information. There are two primary types of providers:

    1. Static Host List Providers: These fetch the host list once during initialization and do not perform subsequent updates. Implement the StaticHostListProvider marker interface to create one.
    2. Dynamic Host List Providers: These continuously update the host list information based on the current database status. Implement the DynamicHostListProvider marker interface to create one.

  10. How the Connection Plugin Manager works

    main

    The Connection Plugin Manager is responsible for managing the lifecycle of plugins and the execution of JDBC operation pipelines. It performs two primary functions:

    1. Plugin Management: It loads and initializes all plugins registered through the configuration.
    2. Pipeline Orchestration: It manages the transition from the initial connection phase to the execution phase.

    Lifecycle Phases

    • Initial Connection Phase: When the manager is initialized, it initiates the host list provider and the connect pipeline. These pipelines establish the host list provider used by all plugins and the initial connection process.
    • Execution Phase: Once the connection is established, all subsequent JDBC method calls trigger the execute pipeline.

    Note: The execute pipeline is not limited to standard SQL execution methods (like executeQuery() or executeUpdate()). It is designed to intercept and process all types of JDBC method calls, including those like ConnectionWrapper.createStatement().

  11. What the Aurora Initial Connection Strategy Plugin does

    main

    The Aurora Initial Connection Strategy Plugin manages how the driver establishes its first connection to an Aurora cluster. It provides two primary benefits:

    1. Configurable Connection Strategies: It allows you to define how the driver selects a host when connecting to a reader cluster or custom cluster endpoint using specific Host Selection Strategies.
    2. Reliable Connection Retrieval: It mitigates issues caused by DNS propagation delays (which can take 40-60 seconds) during failovers. If a user attempts to connect to a cluster endpoint while DNS is still updating, the plugin can replace the outdated endpoint with the correct one.

    Aurora Global Database Support: The plugin recognizes the Aurora Global Writer Endpoint and automatically substitutes it with the current, valid writer endpoint to ensure reliable connectivity even when DNS is updating.