Skip to content

Commit a0d7b99

Browse files
karenc-bqkarenc-bq
committed
chore: standardize to Global Database in documentation
1 parent 8693945 commit a0d7b99

8 files changed

Lines changed: 189 additions & 33 deletions

File tree

‎docs/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@
1616
- [Failover Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFailoverPlugin.md)
1717
- [Failover Configuration Guide](./using-the-nodejs-wrapper/FailoverConfigurationGuide.md)
1818
- [Failover2 Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFailover2Plugin.md)
19-
- [GlobalDb Failover Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheGlobalDbFailoverPlugin.md)
19+
- [Global Database Failover Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheGlobalDbFailoverPlugin.md)
2020
- [Host Monitoring Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheHostMonitoringPlugin.md)
2121
- [Read-Write Splitting Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheReadWriteSplittingPlugin.md)
22-
- [GlobalDb Read-Write Splitting Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheGlobalDbReadWriteSplittingPlugin.md)
22+
- [Global Database Read-Write Splitting Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheGlobalDbReadWriteSplittingPlugin.md)
2323
- [Global Aurora Accessible Regions](./using-the-nodejs-wrapper/using-plugins/UsingGlobalAuroraAccessibleRegions.md)
2424
- [Monitoring Connection Priority](./using-the-nodejs-wrapper/using-plugins/UsingMonitoringConnectionPriority.md)
2525
- [Fastest Response Strategy Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheFastestResponseStrategyPlugin.md)

‎docs/using-the-nodejs-wrapper/GlobalDatabases.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Aurora Global Databases
2+
3+
> **Since version:** 3.0.0
4+
5+
The AWS Advanced NodeJS Wrapper provides comprehensive support for [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/), including both in-region and cross-region failover capabilities.
6+
7+
## Overview
8+
9+
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.
10+
11+
The AWS Advanced NodeJS Wrapper supports:
12+
13+
- In-region failover
14+
- Cross-region planned failover and switchover
15+
- Global writer endpoint recognition
16+
- Stale DNS handling
17+
18+
## Configuration
19+
20+
The following settings 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.
21+
22+
### Writer Connections
23+
24+
**Endpoint:**
25+
Use the global cluster endpoint:
26+
27+
```
28+
<global-db-name>.global-<XYZ>.global.rds.amazonaws.com
29+
```
30+
31+
**Configuration Parameters:**
32+
33+
| Parameter | Value | Notes |
34+
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
35+
| `clusterId` | `1` | See [clusterId parameter documentation](./ClusterId.md) |
36+
| `wrapperDialect` | `global-aurora-mysql` or `global-aurora-pg` | |
37+
| `plugins` | `initialConnection,failover2,efm2` or<br>`initialConnection,gdbFailover,efm2` | Without connection pooling |
38+
| | `auroraConnectionTracker,initialConnection,failover2,efm2` or<br>`auroraConnectionTracker,initialConnection,gdbFailover,efm2` | With connection pooling |
39+
| `globalClusterInstanceHostPatterns` | `?.XYZ1.us-east-2.rds.amazonaws.com,?.XYZ2.us-west-2.rds.amazonaws.com` | See [documentation](./using-plugins/UsingTheFailover2Plugin.md) |
40+
41+
> **Note:** Add additional plugins according to the [compatibility guide](./compatibility/CompatibilityCrossPlugins.md).
42+
43+
### Reader Connections
44+
45+
**Endpoint:**
46+
Use the cluster reader endpoint:
47+
48+
```
49+
<cluster-name>.cluster-ro-<XYZ>.<region>.rds.amazonaws.com
50+
```
51+
52+
**Configuration Parameters:**
53+
54+
| Parameter | Value | Notes |
55+
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
56+
| `clusterId` | `1` | Use the same value as writer connections |
57+
| `wrapperDialect` | `global-aurora-mysql` or `global-aurora-pg` | |
58+
| `plugins` | `initialConnection,failover2,efm2` or<br>`initialConnection,gdbFailover,efm2` | Without connection pooling |
59+
| | `auroraConnectionTracker,initialConnection,failover2,efm2` or<br>`auroraConnectionTracker,initialConnection,gdbFailover,efm2` | With connection pooling |
60+
| `globalClusterInstanceHostPatterns` | Same as writer configuration | |
61+
| `failoverMode` | `strict-reader` or `reader-or-writer` | Depending on system requirements |
62+
63+
> **Note:** Add additional plugins according to the [compatibility guide](./compatibility/CompatibilityCrossPlugins.md).
64+
65+
## Example Configuration
66+
67+
```typescript
68+
// Writer connection
69+
const writerParams = {
70+
host: "my-global-db.global-xyz.global.rds.amazonaws.com",
71+
port: 3306,
72+
database: "mydb",
73+
user: "username",
74+
password: "password",
75+
clusterId: "1",
76+
wrapperDialect: "global-aurora-mysql",
77+
plugins: "initialConnection,failover2,efm2",
78+
globalClusterInstanceHostPatterns: "?.abc123.us-east-1.rds.amazonaws.com,?.def456.us-west-2.rds.amazonaws.com"
79+
};
80+
81+
const writerClient = new AwsMySQLClient(writerParams);
82+
await writerClient.connect();
83+
84+
// Reader connection
85+
const readerParams = {
86+
host: "my-cluster.cluster-ro-xyz.us-east-1.rds.amazonaws.com",
87+
port: 3306,
88+
database: "mydb",
89+
user: "username",
90+
password: "password",
91+
clusterId: "1",
92+
wrapperDialect: "global-aurora-mysql",
93+
plugins: "initialConnection,failover2,efm2",
94+
globalClusterInstanceHostPatterns: "?.abc123.us-east-1.rds.amazonaws.com,?.def456.us-west-2.rds.amazonaws.com",
95+
failoverMode: "strict-reader"
96+
};
97+
98+
const readerClient = new AwsMySQLClient(readerParams);
99+
await readerClient.connect();
100+
```
101+
102+
> For PostgreSQL, use `new AwsPgClient(params)` with `wrapperDialect: "global-aurora-pg"` and port `5432`.
103+
104+
## Important Considerations
105+
106+
### Database instance names
107+
108+
> [!WARNING]
109+
> The plugin does not support duplicate instance names across regions. Ensure that all instance names are unique across all Global Database regions.
110+
111+
### Plugin Selection
112+
113+
- **Connection Pooling**: Include the `auroraConnectionTracker` plugin when using connection pooling.
114+
- The `gdbFailover` plugin has extended failover functionality and supports an application home region.
115+
116+
### Global Cluster Instance Host Patterns
117+
118+
The `globalClusterInstanceHostPatterns` parameter is **required** for Aurora Global Databases. The patterns are based on
119+
instance endpoints. It should contain:
120+
121+
- A comma-separated list of host patterns for each region
122+
- Different cluster identifiers for each region (e.g., `XYZ1`, `XYZ2`)
123+
- Proper region specification for custom domains: `[us-east-1]?.custom.com`
124+
125+
### Failover Behavior
126+
127+
- **In-region failover**: Automatic failover within the same region.
128+
- **Cross-region failover**: Planned failover to a different region.
129+
- **DNS handling**: The `initialConnection` plugin helps mitigate stale DNS issues.
130+
131+
### Restricting Access to Specific Regions
132+
133+
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](./using-plugins/UsingGlobalAuroraAccessibleRegions.md) for details.
134+
135+
### Monitoring Connection Priority
136+
137+
The topology monitor's background connection can be directed to a preferred host type or region using `gdbMonitoringConnectionPriority`. See [Monitoring Connection Priority](./using-plugins/UsingMonitoringConnectionPriority.md) for details.
138+
139+
## Compatibility
140+
141+
For detailed compatibility information, see:
142+
143+
- [Database Types Compatibility](./compatibility/CompatibilityDatabaseTypes.md)
144+
- [Endpoint Types Compatibility](./compatibility/CompatibilityEndpoints.md)
145+
- [Cross-Plugin Compatibility](./compatibility/CompatibilityCrossPlugins.md)
146+
147+
## Related Documentation
148+
149+
- [Global Database Failover Plugin](./using-plugins/UsingTheGlobalDbFailoverPlugin.md)
150+
- [Global Database Read/Write Splitting Plugin](./using-plugins/UsingTheGlobalDbReadWriteSplittingPlugin.md)
151+
- [Failover Plugin v2](./using-plugins/UsingTheFailover2Plugin.md)
152+
- [Aurora Initial Connection Strategy Plugin](./using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md)
153+
- [Restricting Aurora Global Database Access by Region](./using-plugins/UsingGlobalAuroraAccessibleRegions.md)
154+
- [Monitoring Connection Priority](./using-plugins/UsingMonitoringConnectionPriority.md)
155+
- [IAM Authentication Plugin](./using-plugins/UsingTheIamAuthenticationPlugin.md)
156+
- [Database Dialects](./DatabaseDialects.md)

‎docs/using-the-nodejs-wrapper/compatibility/CompatibilityDatabaseTypes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This document is part of the [Compatibility Guide](./Compatibility.md) and expla
44

55
For example, the `limitless` plugin is incompatible with [Aurora Global Database](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database.html) because it's built on different architectural principles than [Limitless Database](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/limitless-architecture.html). Aurora Global Database doesn't use transaction routers and doesn't provide the transaction routers' metadata. This lack of required metadata makes it incompatible with the `limitless` plugin.
66

7-
For Aurora Global Database configuration details, see the [Global Database (GlobalDb) Failover Plugin](../using-plugins/UsingTheGlobalDbFailoverPlugin.md) and [Global Database (GlobalDb) Read/Write Splitting Plugin](../using-plugins/UsingTheGlobalDbReadWriteSplittingPlugin.md) documentation.
7+
For Aurora Global Database configuration details, see the [Global Database Failover Plugin](../using-plugins/UsingTheGlobalDbFailoverPlugin.md) and [Global Database Read/Write Splitting Plugin](../using-plugins/UsingTheGlobalDbReadWriteSplittingPlugin.md) documentation.
88

99
| Plugin codes / Database types | [Aurora Global Database](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database.html) <br>(MySQL and PG) | [Aurora Cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Overview.html) <br>(MySQL and PG) | [RDS Multi-AZ DB Cluster deployment (3 instances)](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) <br>(MySQL and PG) |
1010
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

‎docs/using-the-nodejs-wrapper/using-plugins/UsingGlobalAuroraAccessibleRegions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ The `gdbAccessibleRegions` parameter works alongside the `failoverHomeRegion` pa
5959
> [!WARNING]
6060
> Ensure that `failoverHomeRegion` is included in the `gdbAccessibleRegions` list. Otherwise, home region failover logic will not function correctly.
6161
62-
### Interaction with GlobalDb Read/Write Splitting
62+
### Interaction with Global Database Read/Write Splitting
6363

6464
When using the `gdbReadWriteSplitting` plugin, accessible regions filtering is applied before reader/writer host selection. The `gdbRwHomeRegion` should also be included in the accessible regions list.
6565

‎docs/using-the-nodejs-wrapper/using-plugins/UsingMonitoringConnectionPriority.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,10 @@ Two parameters are available:
1717

1818
## Configuration Parameters
1919

20-
| Parameter | Value | Required | Description | Default Value |
21-
| --------------------------------- | :------: | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
22-
| `monitoringConnectionPriority` | `string` | No | Defines the priority for monitoring connections. Determines which type of host the topology monitor should connect to.<br><br>Possible values: `strict-writer`, `strict-reader`, `writer-or-reader`. | `strict-writer` |
23-
| `gdbMonitoringConnectionPriority` | `string` | No | Defines the priority for monitoring connections in a Global Aurora Database context. Supports region-aware variants and specific region names.<br><br>See [GlobalDb Monitoring Connection Priority Values](#gdb-monitoring-connection-priority-values). | `null` |
20+
| Parameter | Value | Required | Description | Default Value |
21+
| --------------------------------- | :------: | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
22+
| `monitoringConnectionPriority` | `string` | No | Defines the priority for monitoring connections. Determines which type of host the topology monitor should connect to.<br><br>Possible values: `strict-writer`, `strict-reader`, `writer-or-reader`. | `strict-writer` |
23+
| `gdbMonitoringConnectionPriority` | `string` | No | Defines the priority for monitoring connections in a Global Aurora Database context. Supports region-aware variants and specific region names.<br><br>See [Global Database Monitoring Connection Priority Values](#global-database-values-gdbmonitoringconnectionpriority). | `null` |
2424

2525
## Monitoring Connection Priority Values
2626

@@ -32,7 +32,7 @@ Two parameters are available:
3232
| `strict-reader` | The topology monitor connects exclusively to a reader host. If no reader is available, monitoring will fail. |
3333
| `writer-or-reader` | The topology monitor connects to a writer host if available; otherwise falls back to a reader host. |
3434

35-
### GlobalDb Values (`gdbMonitoringConnectionPriority`)
35+
### Global Database Values (`gdbMonitoringConnectionPriority`)
3636

3737
| Value | Description |
3838
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |

0 commit comments

Comments
 (0)