docs: Add docs for RDS Multi-AZ DB Cluster (aws#740)

Bit-Quill · Nov 17, 2023 · 44ed140 · 44ed140
1 parent 6ac6957
commit 44ed140
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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.