Skip to content

Commit 44ed140

Browse files
fanglifangli
authored
docs: Add docs for RDS Multi-AZ DB Cluster (#740)
1 parent 6ac6957 commit 44ed140

File tree

4 files changed

+82
-14
lines changed

4 files changed

+82
-14
lines changed

‎README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ Since a database failover is usually identified by reaching a network or a conne
2929

3030
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).
3131

32+
### Using the AWS JDBC Driver with RDS Multi-AZ DB Clusters
33+
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.
34+
The AWS JDBC Driver has been optimized for such fast failover when working with AWS RDS Multi-AZ DB Clusters.
35+
36+
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.
37+
38+
Visit [this page](./docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md) for more details.
39+
3240
### Using the AWS JDBC Driver with plain RDS databases
3341
The AWS JDBC Driver also works with RDS provided databases that are not Aurora.
3442

‎docs/using-the-jdbc-driver/DatabaseDialects.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,19 @@ The AWS Advanced JDBC Driver is a wrapper that requires an underlying driver, an
1515
### List of Available Dialect Codes
1616
Dialect codes specify what kind of database any connections will be made to.
1717

18-
| Dialect Code Reference | Value | Database |
19-
|------------------------|----------------|------------------------------------------------------------------------------------------------|
20-
| `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL |
21-
| `RDS_MYSQL` | `rds-mysql` | Amazon RDS MySQL |
22-
| `MYSQL` | `mysql` | MySQL |
23-
| `AURORA_PG` | `aurora-pg` | Aurora PostgreSQL |
24-
| `RDS_PG` | `rds-pg` | Amazon RDS PostgreSQL |
25-
| `PG` | `pg` | PostgreSQL |
26-
| `MARIADB` | `mariadb` | MariaDB |
27-
| `CUSTOM` | `custom` | See [custom dialects](#custom-dialects). This code is not required when using custom dialects. |
28-
| `UNKNOWN` | `unknown` | Unknown. Although this code is available, do not use it as it will result in errors. |
18+
| Dialect Code Reference | Value | Database |
19+
| ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
20+
| `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL |
21+
| `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) |
22+
| `RDS_MYSQL` | `rds-mysql` | Amazon RDS MySQL |
23+
| `MYSQL` | `mysql` | MySQL |
24+
| `AURORA_PG` | `aurora-pg` | Aurora PostgreSQL |
25+
| `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) |
26+
| `RDS_PG` | `rds-pg` | Amazon RDS PostgreSQL |
27+
| `PG` | `pg` | PostgreSQL |
28+
| `MARIADB` | `mariadb` | MariaDB |
29+
| `CUSTOM` | `custom` | See [custom dialects](#custom-dialects). This code is not required when using custom dialects. |
30+
| `UNKNOWN` | `unknown` | Unknown. Although this code is available, do not use it as it will result in errors. |
2931

3032
## Custom Dialects
3133
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.

‎docs/using-the-jdbc-driver/SupportForRDSMultiAzDBCluster.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Enhanced Support for Amazon RDS Multi-AZ DB Cluster
2+
3+
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.
4+
5+
## General Usage
6+
7+
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.
8+
9+
### MySQL
10+
11+
Preparing a connection with MySQL in a Multi-AZ Cluster remains the same as before:
12+
13+
```java
14+
Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:mysql://cluster-writer-endpoint[:port]/database", props);
15+
```
16+
17+
### PostgreSQL
18+
19+
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.
20+
21+
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:
22+
23+
```sql
24+
CREATE EXTENSION rds_tools;
25+
```
26+
27+
Then, prepare the connection with:
28+
29+
```java
30+
Connection conn = DriverManager.getConnection("jdbc:aws-wrapper:postgresql://cluster-writer-endpoint[:port]/database", props);
31+
```
32+
33+
## Optimizing Switchover Time
34+
35+
Amazon RDS Multi-AZ with two readable standbys now supports minor version upgrades with 1 second of downtime.
36+
37+
See feature announcement [here](https://aws.amazon.com/about-aws/whats-new/2023/11/amazon-rds-multi-az-two-stanbys-upgrades-downtime/).
38+
39+
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.
40+
41+
For more details on the `failover` plugin configuration, refer to the [Failover Configuration Guide](/docs/using-the-jdbc-driver/FailoverConfigurationGuide.md).
42+
43+
## Examples
44+
45+
We have created many examples in the [examples](/examples) folder demonstrating how to use the driver.
46+
47+
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/).
48+
49+
## Limitations
50+
51+
The following plugins have been tested and confirmed to work with Amazon RDS Multi-AZ DB Clusters:
52+
53+
* [Aurora Connection Tracker Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
54+
* [Failover Connection Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheFailoverPlugin.md)
55+
* [Host Monitoring Connection Plugin](/docs/using-the-jdbc-driver/using-plugins/UsingTheHostMonitoringPlugin.md)
56+
57+
The compatibility of other plugins has not been tested at this time. They may function as expected or potentially result in unhandled behavior.
58+
Use at your own discretion.

0 commit comments

Comments
 (0)