From 44ed140fe5d3a33e56a73680c240ecfa825553b5 Mon Sep 17 00:00:00 2001 From: Fang Li Date: Fri, 17 Nov 2023 11:24:48 -0800 Subject: [PATCH] docs: Add docs for RDS Multi-AZ DB Cluster (#740) --- README.md | 8 +++ .../using-the-jdbc-driver/DatabaseDialects.md | 24 ++++---- .../SupportForRDSMultiAzDBCluster.md | 58 +++++++++++++++++++ .../UsingTheJdbcDriver.md | 6 +- 4 files changed, 82 insertions(+), 14 deletions(-) create mode 100644 docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md diff --git a/README.md b/README.md index 6911a5dc1..0b3294d3f 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,14 @@ Since a database failover is usually identified by reaching a network or a conne Enhanced Failure Monitoring (EFM) is a feature available from the [Host Monitoring Connection Plugin](./docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md#enhanced-failure-monitoring) that periodically checks the connected database node's health and availability. If a database node is determined to be unhealthy, the connection is aborted (and potentially routed to another healthy node in the cluster). +### Using the AWS JDBC Driver with RDS Multi-AZ DB Clusters +The [AWS RDS Multi-AZ DB Clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) are capable of switching over the current writer node to another node in the cluster within approximately 1 second or less, in case of minor engine version upgrade or OS maintenance operations. +The AWS JDBC Driver has been optimized for such fast failover when working with AWS RDS Multi-AZ DB Clusters. + +With the `failover` plugin, the downtime during certain DB cluster operations, such as engine minor version upgrades, can be reduced to one second or even less with finely tuned parameters. It supports both MySQL and PostgreSQL clusters. + +Visit [this page](./docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md) for more details. + ### Using the AWS JDBC Driver with plain RDS databases The AWS JDBC Driver also works with RDS provided databases that are not Aurora. diff --git a/docs/using-the-jdbc-driver/DatabaseDialects.md b/docs/using-the-jdbc-driver/DatabaseDialects.md index 467c4112b..04b6ace51 100644 --- a/docs/using-the-jdbc-driver/DatabaseDialects.md +++ b/docs/using-the-jdbc-driver/DatabaseDialects.md @@ -15,17 +15,19 @@ The AWS Advanced JDBC Driver is a wrapper that requires an underlying driver, an ### List of Available Dialect Codes Dialect codes specify what kind of database any connections will be made to. -| Dialect Code Reference | Value | Database | -|------------------------|----------------|------------------------------------------------------------------------------------------------| -| `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL | -| `RDS_MYSQL` | `rds-mysql` | Amazon RDS MySQL | -| `MYSQL` | `mysql` | MySQL | -| `AURORA_PG` | `aurora-pg` | Aurora PostgreSQL | -| `RDS_PG` | `rds-pg` | Amazon RDS PostgreSQL | -| `PG` | `pg` | PostgreSQL | -| `MARIADB` | `mariadb` | MariaDB | -| `CUSTOM` | `custom` | See [custom dialects](#custom-dialects). This code is not required when using custom dialects. | -| `UNKNOWN` | `unknown` | Unknown. Although this code is available, do not use it as it will result in errors. | +| Dialect Code Reference | Value | Database | +| ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL | +| `RDS_MULTI_AZ_MYSQL_CLUSTER` | `rds-multi-az-mysql-cluster` | [Amazon RDS MySQL Multi-AZ DB Cluster Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) | +| `RDS_MYSQL` | `rds-mysql` | Amazon RDS MySQL | +| `MYSQL` | `mysql` | MySQL | +| `AURORA_PG` | `aurora-pg` | Aurora PostgreSQL | +| `RDS_MULTI_AZ_PG_CLUSTER` | `rds-multi-az-pg-cluster` | [Amazon RDS PostgreSQL Multi-AZ DB Cluster Deployments](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) | +| `RDS_PG` | `rds-pg` | Amazon RDS PostgreSQL | +| `PG` | `pg` | PostgreSQL | +| `MARIADB` | `mariadb` | MariaDB | +| `CUSTOM` | `custom` | See [custom dialects](#custom-dialects). This code is not required when using custom dialects. | +| `UNKNOWN` | `unknown` | Unknown. Although this code is available, do not use it as it will result in errors. | ## Custom Dialects If you are interested in using the AWS JDBC Driver but your desired database type is not currently supported, it is possible to create a custom dialect. diff --git a/docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md b/docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md new file mode 100644 index 000000000..ee0f68963 --- /dev/null +++ b/docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md @@ -0,0 +1,58 @@ +# Enhanced Support for Amazon RDS Multi-AZ DB Cluster + +As of [v2.3.0](https://github.com/awslabs/aws-advanced-jdbc-wrapper/releases/tag/2.3.0), the AWS JDBC Driver has expanded its support for Amazon RDS Multi-AZ DB Cluster Deployment. By leveraging the topology information within the RDS Multi-AZ DB Cluster, the driver is capable of switching over the connection to a new writer node in approximately 1 second or less, given there is no replica lag during minor version upgrades or OS maintenance upgrades. + +## General Usage + +The process of using the AWS JDBC Driver with RDS Multi-AZ DB Cluster is the same as using it with an RDS Aurora cluster. All properties, configurations, functions, etc., remain consistent. Instead of connecting to a generic database endpoint, simply replace the endpoint with the Cluster Writer Endpoint provided by the RDS Multi-AZ DB Cluster. + +### MySQL + +Preparing a connection with MySQL in a Multi-AZ Cluster remains the same as before: + +```java +Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:mysql://cluster-writer-endpoint[:port]/database", props); +``` + +### PostgreSQL + +The topology information is populated in Amazon RDS for PostgreSQL versions 13.12, 14.9, 15.4, or higher, starting from revision R3. Ensure you have a supported PostgreSQL version deployed. + +Per AWS documentation and [this blog post](https://aws.amazon.com/blogs/database/achieve-one-second-or-less-downtime-with-the-advanced-jdbc-wrapper-driver-when-upgrading-amazon-rds-multi-az-db-clusters/), the `rds_tools` extension must be manually installed using the following DDL before the topology information becomes available on target cluster: + +```sql +CREATE EXTENSION rds_tools; +``` + +Then, prepare the connection with: + +```java +Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:postgresql://cluster-writer-endpoint[:port]/database", props); +``` + +## Optimizing Switchover Time + +Amazon RDS Multi-AZ with two readable standbys now supports minor version upgrades with 1 second of downtime. + +See feature announcement [here](https://aws.amazon.com/about-aws/whats-new/2023/11/amazon-rds-multi-az-two-stanbys-upgrades-downtime/). + +During minor version upgrades of RDS Multi-AZ DB clusters, the `failover` plugin switches the connection from the current writer to a newly upgraded reader. If minimizing downtime during switchover is critical to your application, consider adjusting the `failoverClusterTopologyRefreshRateMs` to a lower value such as 100ms, from the default 2000ms. However, be aware that this can potentially increase the workload on the database during the switchover. + +For more details on the `failover` plugin configuration, refer to the [Failover Configuration Guide](/docs/using-the-jdbc-driver/FailoverConfigurationGuide.md). + +## Examples + +We have created many examples in the [examples](/examples) folder demonstrating how to use the driver. + +For additional information, you may also refer to [this AWS blog post](https://aws.amazon.com/blogs/database/achieve-one-second-or-less-downtime-with-the-advanced-jdbc-wrapper-driver-when-upgrading-amazon-rds-multi-az-db-clusters/). + +## Limitations + +The following plugins have been tested and confirmed to work with Amazon RDS Multi-AZ DB Clusters: + +* [Aurora Connection Tracker Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) +* [Failover Connection Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md) +* [Host Monitoring Connection Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md) + +The compatibility of other plugins has not been tested at this time. They may function as expected or potentially result in unhandled behavior. +Use at your own discretion. diff --git a/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md b/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md index de1ab0059..576fd3c5a 100644 --- a/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md +++ b/docs/using-the-jdbc-driver/UsingTheJdbcDriver.md @@ -127,15 +127,15 @@ The AWS JDBC Driver has several built-in plugins that are available to use. Plea | Plugin name | Plugin Code | Database Compatibility | Description | Additional Required Dependencies | |------------------------------------------------------------------------------------------------|---------------------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Failover Connection Plugin](./using-plugins/UsingTheFailoverPlugin.md) | `failover` | Aurora | Enables the failover functionality supported by Amazon Aurora clusters. Prevents opening a wrong connection to an old writer node dues to stale DNS after failover event. This plugin is enabled by default. | None | -| [Host Monitoring Connection Plugin](./using-plugins/UsingTheHostMonitoringPlugin.md) | `efm` | Aurora | Enables enhanced host connection failure monitoring, allowing faster failure detection rates. This plugin is enabled by default. | None | +| [Failover Connection Plugin](./using-plugins/UsingTheFailoverPlugin.md) | `failover` | Aurora, RDS Multi-AZ DB Cluster | Enables the failover functionality supported by Amazon Aurora clusters and RDS Multi-AZ DB clusters. Prevents opening a wrong connection to an old writer node dues to stale DNS after failover event. This plugin is enabled by default. | None | +| [Host Monitoring Connection Plugin](./using-plugins/UsingTheHostMonitoringPlugin.md) | `efm` | Aurora, RDS Multi-AZ DB Cluster | Enables enhanced host connection failure monitoring, allowing faster failure detection rates. This plugin is enabled by default. | None | | Data Cache Connection Plugin | `dataCache` | Any database | Caches results from SQL queries matching the regular expression specified in the `dataCacheTriggerCondition` configuration parameter. | None | | Execution Time Connection Plugin | `executionTime` | Any database | Logs the time taken to execute any JDBC method. | None | | Log Query Connection Plugin | `logQuery` | Any database | Tracks and logs the SQL statements to be executed. Sometimes SQL statements are not passed directly to the JDBC method as a parameter, such as [executeBatch()](https://docs.oracle.com/javase/8/docs/api/java/sql/Statement.html#executeBatch--). Users can set `enhancedLogQueryEnabled` to `true`, allowing the JDBC Wrapper to obtain SQL statements via Java Reflection.

:warning:**Note:** Enabling Java Reflection may cause a performance degradation. | None | | [IAM Authentication Connection Plugin](./using-plugins/UsingTheIamAuthenticationPlugin.md) | `iam` | Any database | Enables users to connect to their Amazon Aurora clusters using AWS Identity and Access Management (IAM). | [AWS Java SDK RDS v2.x](https://central.sonatype.com/artifact/software.amazon.awssdk/rds) | | [AWS Secrets Manager Connection Plugin](./using-plugins/UsingTheAwsSecretsManagerPlugin.md) | `awsSecretsManager` | Any database | Enables fetching database credentials from the AWS Secrets Manager service. | [Jackson Databind](https://central.sonatype.com/artifact/com.fasterxml.jackson.core/jackson-databind)
[AWS Secrets Manager](https://central.sonatype.com/artifact/software.amazon.awssdk/secretsmanager) | | Aurora Stale DNS Plugin | `auroraStaleDns` | Aurora | Prevents incorrectly opening a new connection to an old writer node when DNS records have not yet updated after a recent failover event.

:warning:**Note:** Contrary to `failover` plugin, `auroraStaleDns` plugin doesn't implement failover support itself. It helps to eliminate opening wrong connections to an old writer node after cluster failover is completed.

:warning:**Note:** This logic is already included in `failover` plugin so you can omit using both plugins at the same time. | None | -| [Aurora Connection Tracker Plugin](./using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | `auroraConnectionTracker` | Aurora | Tracks all the opened connections. In the event of a cluster failover, the plugin will close all the impacted connections to the node. This plugin is enabled by default. | None | +| [Aurora Connection Tracker Plugin](./using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | `auroraConnectionTracker` | Aurora, RDS Multi-AZ DB Cluster | Tracks all the opened connections. In the event of a cluster failover, the plugin will close all the impacted connections to the node. This plugin is enabled by default. | None | | [Driver Metadata Connection Plugin](./using-plugins/UsingTheDriverMetadataConnectionPlugin.md) | `driverMetaData` | Any database | Allows user application to override the return value of `DatabaseMetaData#getDriverName` | None | | [Read Write Splitting Plugin](./using-plugins/UsingTheReadWriteSplittingPlugin.md) | `readWriteSplitting` | Aurora | Enables read write splitting functionality where users can switch between database reader and writer instances. | None | | [Developer Plugin](./using-plugins/UsingTheDeveloperPlugin.md) | `dev` | Any database | Helps developers test various everyday scenarios including rare events like network outages and database cluster failover. The plugin allows injecting and raising an expected exception, then verifying how applications handle it. | None |