diff --git a/README.md b/README.md index fd0c32154..49983bf79 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,7 @@ The following table lists the connection properties used with the AWS Advanced P | `topology_refresh_ms` | [Driver Parameters](docs/using-the-python-wrapper/UsingThePythonWrapper.md#aws-advanced-python-wrapper-parameters) | | `cluster_id` | [Driver Parameters](docs/using-the-python-wrapper/UsingThePythonWrapper.md#aws-advanced-python-wrapper-parameters) | | `cluster_instance_host_pattern` | [Driver Parameters](docs/using-the-python-wrapper/UsingThePythonWrapper.md#aws-advanced-python-wrapper-parameters) | +| `global_cluster_instance_host_patterns` | [Failover v2 Plugin](docs/using-the-python-wrapper/UsingThePythonWrapper.md#aws-advanced-python-wrapper-parameters) | | `wrapper_dialect` | [Dialects](docs/using-the-python-wrapper/DatabaseDialects.md), and whether you should include it. | | `wrapper_driver_dialect` | [Driver Dialect](./docs/using-the-python-wrapper/DriverDialects.md), and whether you should include it. | | `plugins` | [Connection Plugin Manager](docs/using-the-python-wrapper/UsingThePythonWrapper.md#connection-plugin-manager-parameters) | diff --git a/docs/README.md b/docs/README.md index 2cfbd23bb..a68c8f452 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,8 @@ - [Session State](using-the-python-wrapper/SessionState.md) - [Database Dialects](using-the-python-wrapper/DatabaseDialects.md) - [Driver Dialects](using-the-python-wrapper/DriverDialects.md) + - [Cluster ID](using-the-python-wrapper/ClusterId.md) + - [Aurora Global Databases](using-the-python-wrapper/GlobalDatabases.md) - [Telemetry](using-the-python-wrapper/Telemetry.md) - [Plugins](using-the-python-wrapper/UsingThePythonWrapper.md#plugins) - [Failover Plugin](using-the-python-wrapper/using-plugins/UsingTheFailoverPlugin.md) diff --git a/docs/images/cluster_id_one_cluster_example.png b/docs/images/cluster_id_one_cluster_example.png new file mode 100644 index 000000000..590f31a65 Binary files /dev/null and b/docs/images/cluster_id_one_cluster_example.png differ diff --git a/docs/images/cluster_id_two_cluster_example.png b/docs/images/cluster_id_two_cluster_example.png new file mode 100644 index 000000000..801fad7e5 Binary files /dev/null and b/docs/images/cluster_id_two_cluster_example.png differ diff --git a/docs/using-the-python-wrapper/ClusterId.md b/docs/using-the-python-wrapper/ClusterId.md new file mode 100644 index 000000000..e4167c039 --- /dev/null +++ b/docs/using-the-python-wrapper/ClusterId.md @@ -0,0 +1,240 @@ +# Understanding the cluster_id Parameter + +## Overview + +The `cluster_id` parameter is a critical configuration setting when using the AWS Advanced Python Wrapper to **connect to multiple database clusters within a single application**. This parameter serves as a unique identifier that enables the wrapper to maintain separate caches and state for each distinct database cluster your application connects to. + +## What is a Cluster? + +Understanding what constitutes a cluster is crucial for correctly setting the `cluster_id` parameter. In the context of the AWS Advanced Python Wrapper, a **cluster** is a logical grouping of database instances that should share the same topology cache and monitoring services. + +A cluster represents one writer instance (primary) and zero or more reader instances (replicas). These make up shared topology that the wrapper needs to track, and are the group of instances the wrapper can reconnect to when a failover is detected. + +### Examples of Clusters + +- Aurora DB Cluster (one writer + multiple readers) +- RDS Multi-AZ DB Cluster (one writer + two readers) +- Aurora Global Database (when supplying a global db endpoint, the wrapper considers them as a single cluster) + +> **Rule of thumb:** If the wrapper should track separate topology information and perform independent failover operations, use different `cluster_id` values. If instances share the same topology and failover domain, use the same `cluster_id`. + +## Why cluster_id is Important + +The AWS Advanced Python Wrapper uses the `cluster_id` as a **key for internal caching mechanisms** to optimize performance and maintain cluster-specific state. Without proper `cluster_id` configuration, your application may experience: + +- Cache collisions between different clusters +- Incorrect topology information +- Degraded performance due to cache invalidation + +## Why Not Use AWS DB Cluster Identifiers? + +Host information can take many forms: + +- **IP Address Connections:** `10.0.1.50` ← No cluster info! +- **Custom Domain Names:** `db.mycompany.com` ← Custom domain +- **Custom Endpoints:** `my-custom-endpoint.cluster-custom-abc.us-east-1.rds.amazonaws.com` ← Custom endpoint +- **Proxy Connections:** `my-proxy.proxy-abc.us-east-1.rds.amazonaws.com` ← Proxy, not actual cluster + +In fact, all of these could reference the exact same cluster. Therefore, because the wrapper cannot reliably parse cluster information from all connection types, **it is up to the user to explicitly provide the `cluster_id`**. + +## How cluster_id is Used Internally + +The wrapper uses `cluster_id` as a cache key for topology information and monitoring services. This enables multiple connections to the same cluster to share cached data and avoid redundant db meta-data. + +### Example: Single Cluster with Multiple Connections + +The following diagram shows how connections with the same `cluster_id` share cached resources: + +![Single Cluster Example](../images/cluster_id_one_cluster_example.png) + +**Key Points:** +- Three connections use different connection strings (custom endpoint, IP address, cluster endpoint) but all specify **`cluster_id="foo"`** +- All three connections share the same Topology Cache and Monitor Threads in the wrapper +- The Topology Cache stores a key-value mapping where `"foo"` maps to `["instance-1", "instance-2", "instance-3"]` +- Despite different connection URLs, all connections monitor and query the same physical database cluster + +**The Impact:** +Shared resources eliminate redundant topology queries and reduce monitoring overhead. + +### Example: Multiple Clusters with Separate Cache Isolation + +The following diagram shows how different `cluster_id` values maintain separate caches for different clusters. + +![Two Cluster Example](../images/cluster_id_two_cluster_example.png) + +**Key Points:** +- Connection 1 and 3 use **`cluster_id="foo"`** and share the same cache entries +- Connection 2 uses **`cluster_id="bar"`** and has completely separate cache entries +- Each `cluster_id` acts as a key in the cache dictionary +- Topology Cache maintains separate entries: `"foo"` → `[instance-1, instance-2, instance-3]` and `"bar"` → `[instance-4, instance-5]` +- Monitor Cache maintains separate monitor threads for each cluster +- Monitors poll their respective database clusters and update the corresponding topology cache entries + +**The Impact:** +This isolation prevents cache collisions and ensures correct failover behavior for each cluster. + +## When to Specify cluster_id + +### Required: Multiple Clusters in One Application + +You **must** specify a unique `cluster_id` for every DB cluster when your application connects to multiple database clusters: + +```python +from aws_advanced_python_wrapper import AwsWrapperConnection +from psycopg import Connection + +# Source cluster connection +with AwsWrapperConnection.connect( + Connection.connect, + "host=source-db.us-east-1.rds.amazonaws.com dbname=mydb user=admin password=pwd", + cluster_id="source-cluster", + autocommit=True +) as source_conn: + source_cursor = source_conn.cursor() + source_cursor.execute("SELECT * FROM users") + rows = source_cursor.fetchall() + +# Destination cluster connection - different cluster_id! +with AwsWrapperConnection.connect( + Connection.connect, + "host=dest-db.us-west-2.rds.amazonaws.com dbname=mydb user=admin password=pwd", + cluster_id="destination-cluster", + autocommit=True +) as dest_conn: + dest_cursor = dest_conn.cursor() + # ... migration logic + +# Connecting to source-db via IP - same cluster_id as source_conn +with AwsWrapperConnection.connect( + Connection.connect, + "host=10.0.0.1 dbname=mydb user=admin password=pwd", + cluster_id="source-cluster", + autocommit=True +) as source_ip_conn: + pass +``` + +### Optional: Single Cluster Applications + +If your application only connects to one cluster, you can omit `cluster_id` (defaults to `"1"`): + +```python +from aws_advanced_python_wrapper import AwsWrapperConnection +from psycopg import Connection + +# Single cluster - cluster_id defaults to "1" +with AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=mydb user=admin password=pwd", + autocommit=True +) as conn: + cursor = conn.cursor() + cursor.execute("SELECT 1") +``` + +This also includes if you have multiple connections using different host information: + +```python +# cluster_id defaults to "1" +with AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=mydb user=admin password=pwd", + autocommit=True +) as url_conn: + pass + +# "10.0.0.1" -> IP address of my-cluster. Same cluster, so default cluster_id "1" is fine. +with AwsWrapperConnection.connect( + Connection.connect, + "host=10.0.0.1 dbname=mydb user=admin password=pwd", + autocommit=True +) as ip_conn: + pass +``` + +## Critical Warnings + +### NEVER Share cluster_id Between Different Clusters + +Using the same `cluster_id` for different database clusters will cause serious issues: + +```python +# ❌ WRONG - Same cluster_id for different clusters +source_conn = AwsWrapperConnection.connect( + Connection.connect, + "host=source-db.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="shared-id" # ← BAD! +) + +dest_conn = AwsWrapperConnection.connect( + Connection.connect, + "host=dest-db.us-west-2.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="shared-id" # ← BAD! Same ID for different cluster +) +``` + +**Problems this causes:** +- Topology cache collision (dest-db's topology could overwrite source-db's) +- Incorrect failover behavior (wrapper may try to failover to wrong cluster) +- Monitor conflicts (Only one monitor instance for both clusters will lead to undefined results) + +**Correct approach:** +```python +# ✅ CORRECT - Unique cluster_id for each cluster +source_conn = AwsWrapperConnection.connect( + Connection.connect, + "host=source-db.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="source-cluster" +) + +dest_conn = AwsWrapperConnection.connect( + Connection.connect, + "host=dest-db.us-west-2.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="destination-cluster" +) +``` + +### Always Use Same cluster_id for Same Cluster + +Using different `cluster_id` values for the same cluster reduces efficiency: + +```python +# ⚠️ SUBOPTIMAL - Different cluster_ids for same cluster +conn1 = AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="my-cluster-1" +) + +conn2 = AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id="my-cluster-2" # Different ID for same cluster +) +``` + +**Problems this causes:** +- Duplication of caches +- Multiple monitoring threads for the same cluster + +**Best practice:** +```python +# ✅ BEST - Same cluster_id for same cluster +CLUSTER_ID = "my-cluster" + +conn1 = AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id=CLUSTER_ID +) + +conn2 = AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.us-east-1.rds.amazonaws.com dbname=db user=admin password=pwd", + cluster_id=CLUSTER_ID # Shared cache and resources +) +``` + +## Summary + +The `cluster_id` parameter is essential for applications connecting to multiple database clusters. It serves as a cache key for topology information and monitoring services. Always use unique `cluster_id` values for different clusters, and consistent values for the same cluster to maximize performance and avoid conflicts. diff --git a/docs/using-the-python-wrapper/DatabaseDialects.md b/docs/using-the-python-wrapper/DatabaseDialects.md index ec77928ff..6ab20af0b 100644 --- a/docs/using-the-python-wrapper/DatabaseDialects.md +++ b/docs/using-the-python-wrapper/DatabaseDialects.md @@ -23,10 +23,12 @@ Dialect codes specify what kind of database any connections will be made to. | Dialect Code Reference | Value | Database | |------------------------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `AURORA_MYSQL` | `aurora-mysql` | Aurora MySQL | +| `GLOBAL_AURORA_MYSQL` | `global-aurora-mysql` | [Aurora Global Database MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-getting-started.html) | | `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 | +| `GLOBAL_AURORA_PG` | `global-aurora-pg` | [Aurora Global Database PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-global-database-getting-started.html) | | `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 | diff --git a/docs/using-the-python-wrapper/GlobalDatabases.md b/docs/using-the-python-wrapper/GlobalDatabases.md new file mode 100644 index 000000000..90e4a7d2c --- /dev/null +++ b/docs/using-the-python-wrapper/GlobalDatabases.md @@ -0,0 +1,129 @@ +# Aurora Global Databases + +The AWS Advanced Python Wrapper provides support for [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/). + +## Overview + +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. + +The AWS Advanced Python Wrapper supports Global Writer Endpoint recognition. + +## Configuration + +The following instructions are recommended by AWS Service Teams for Aurora Global Database connections. + +### Writer Connections + +**Connection String:** +Use the global cluster endpoint: +``` +.global-.global.rds.amazonaws.com +``` + +**Configuration Parameters:** + +| Parameter | Value | Notes | +|------------------------------------------|--------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| +| `cluster_id` | `1` | See [cluster_id parameter documentation](./ClusterId.md) | +| `wrapper_dialect` | `global-aurora-mysql` or `global-aurora-pg` | | +| `plugins` | `initial_connection,failover2,efm2` | Without connection pooling | +| | `aurora_connection_tracker,initial_connection,failover2,efm2` | With connection pooling | +| `global_cluster_instance_host_patterns` | `us-east-2:?.XYZ1.us-east-2.rds.amazonaws.com,us-west-2:?.XYZ2.us-west-2.rds.amazonaws.com` | See [documentation](./using-plugins/UsingTheFailover2Plugin.md) | + +> **Note:** Add additional plugins as needed for your use case. + +### Reader Connections + +**Connection String:** +Use the cluster reader endpoint: +``` +.cluster-ro-..rds.amazonaws.com +``` + +**Configuration Parameters:** + +| Parameter | Value | Notes | +|------------------------------------------|--------------------------------------------------------------------------------|------------------------------------------| +| `cluster_id` | `1` | Use the same value as writer connections | +| `wrapper_dialect` | `global-aurora-mysql` or `global-aurora-pg` | | +| `plugins` | `initial_connection,failover2,efm2` | Without connection pooling | +| | `aurora_connection_tracker,initial_connection,failover2,efm2` | With connection pooling | +| `global_cluster_instance_host_patterns` | Same as writer configuration | | +| `failover_mode` | `strict-reader` or `reader-or-writer` | Depending on system requirements | + +> **Note:** Add additional plugins as needed for your use case. + +## Example Configuration + +### PostgreSQL Example + +```python +from aws_advanced_python_wrapper import AwsWrapperConnection +from psycopg import Connection + +# Writer connection +with AwsWrapperConnection.connect( + Connection.connect, + "host=my-global-db.global-xyz.global.rds.amazonaws.com dbname=mydb user=admin password=pwd", + plugins="initial_connection,failover2,efm2", + wrapper_dialect="global-aurora-pg", + cluster_id="1", + global_cluster_instance_host_patterns="us-east-1:?.abc123.us-east-1.rds.amazonaws.com,us-west-2:?.def456.us-west-2.rds.amazonaws.com", + autocommit=True +) as awsconn: + awscursor = awsconn.cursor() + awscursor.execute("SELECT pg_catalog.aurora_db_instance_identifier()") + print(awscursor.fetchone()) + +# Reader connection +with AwsWrapperConnection.connect( + Connection.connect, + "host=my-cluster.cluster-ro-abc123.us-east-1.rds.amazonaws.com dbname=mydb user=admin password=pwd", + plugins="initial_connection,failover2,efm2", + wrapper_dialect="global-aurora-pg", + cluster_id="1", + global_cluster_instance_host_patterns="us-east-1:?.abc123.us-east-1.rds.amazonaws.com,us-west-2:?.def456.us-west-2.rds.amazonaws.com", + failover_mode="strict-reader", + autocommit=True +) as awsconn: + awscursor = awsconn.cursor() + awscursor.execute("SELECT pg_catalog.aurora_db_instance_identifier()") + print(awscursor.fetchone()) +``` + +### MySQL Example + +```python +from aws_advanced_python_wrapper import AwsWrapperConnection +from mysql.connector import Connect + +# Writer connection +with AwsWrapperConnection.connect( + Connect, + "host=my-global-db.global-xyz.global.rds.amazonaws.com database=mydb user=admin password=pwd", + plugins="initial_connection,failover2,efm2", + wrapper_dialect="global-aurora-mysql", + cluster_id="1", + global_cluster_instance_host_patterns="us-east-1:?.abc123.us-east-1.rds.amazonaws.com,us-west-2:?.def456.us-west-2.rds.amazonaws.com", + autocommit=True +) as awsconn: + awscursor = awsconn.cursor() + awscursor.execute("SELECT @@aurora_server_id") + print(awscursor.fetchone()) +``` + +## Important Considerations + +### Plugin Selection +- **Connection Pooling**: Include the `aurora_connection_tracker` plugin when using connection pooling. + +### Global Cluster Instance Host Patterns +The `global_cluster_instance_host_patterns` parameter is **required** for Aurora Global Databases. Each entry uses the format `:` or `::`. It should contain: +- Comma-separated list of region-prefixed host patterns for each region +- Different cluster identifiers for each region (e.g., `XYZ1`, `XYZ2`) +- Example: `us-east-2:?.XYZ1.us-east-2.rds.amazonaws.com,us-west-2:?.XYZ2.us-west-2.rds.amazonaws.com` + +### Authentication Plugins Compatible with GDB +- [IAM Authentication Plugin](./using-plugins/UsingTheIamAuthenticationPlugin.md) +- [Federated Authentication Plugin](./using-plugins/UsingTheFederatedAuthPlugin.md) +- [Okta Authentication Plugin](./using-plugins/UsingTheOktaAuthPlugin.md) diff --git a/docs/using-the-python-wrapper/UsingThePythonWrapper.md b/docs/using-the-python-wrapper/UsingThePythonWrapper.md index 83bfb0670..fc47f6027 100644 --- a/docs/using-the-python-wrapper/UsingThePythonWrapper.md +++ b/docs/using-the-python-wrapper/UsingThePythonWrapper.md @@ -28,7 +28,8 @@ These parameters are applicable to any instance of the AWS Advanced Python Wrapp | auxiliary_query_timeout_sec | Network timeout, in seconds, used for auxiliary queries to the database. This timeout applies to queries executed by the wrapper driver to gain info about the connected database. It does not apply to queries requested by the driver client. | False | 5 | | topology_refresh_ms | Cluster topology refresh rate in milliseconds. The cached topology for the cluster will be invalidated after the specified time, after which it will be updated during the next interaction with the connection. | False | 30000 | | cluster_id | A unique identifier for the cluster. Connections with the same cluster id share a cluster topology cache. If unspecified, a cluster id is automatically created for AWS RDS clusters. | False | None | -| cluster_instance_host_pattern | The cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for cluster instance names. This pattern is required to be specified for IP address or custom domain connections to AWS RDS clusters. Otherwise, if unspecified, the pattern will be automatically created for AWS RDS clusters. | False | 30000 | +| cluster_instance_host_pattern | The cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for cluster instance names. This pattern is required to be specified for IP address or custom domain connections to AWS RDS clusters. Otherwise, if unspecified, the pattern will be automatically created for AWS RDS clusters. | False | None | +| global_cluster_instance_host_patterns | A comma-separated list of instance host patterns for Aurora Global Databases, with entries in the format `:` or `::`. A "?" character in the host pattern should be used as a placeholder for DB instance identifiers. The list should contain host patterns for each region of the global database. This parameter is required for Aurora Global Databases and is ignored for other database types. | False | None | | transfer_session_state_on_switch | Enables transferring the session state to a new connection. | False | `True` | | reset_session_state_on_close | Enables resetting the session state before closing connection. | False | `True` | | rollback_on_switch | Enables rolling back a current transaction, if any in effect, before switching to a new connection. | False | `True` | diff --git a/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md b/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md index e3ae6bd87..1b7e6d6cf 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md @@ -58,6 +58,7 @@ In addition to the parameters that you can configure for the underlying driver, |------------------------------------------|:-------:|:--------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `failover_mode` | String | No | Defines a mode for failover process. Failover process may prioritize hosts with different roles and connect to them. Possible values:

- `strict-writer` - Failover process follows writer host and connects to a new writer when it changes.
- `reader-or-writer` - During failover, the wrapper tries to connect to any available/accessible reader host. If no reader is available, the wrapper will connect to a writer host. This logic mimics the logic of the Aurora read-only cluster endpoint.
- `strict-reader` - During failover, the wrapper tries to connect to any available reader host. If no reader is available, the wrapper raises an error. Reader failover to a writer host will only be allowed for single-host clusters. This logic mimics the logic of the Aurora read-only cluster endpoint. | Default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader-or-writer`. Otherwise, it's `strict-writer`. | | `cluster_instance_host_pattern` | String | If connecting using an IP address or custom domain URL: Yes

Otherwise: No | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster. See [here](./UsingTheFailoverPlugin.md#host-pattern) for more information.

Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`

Use case Example: If your cluster instance endpoints follow this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection parameters should look like this: `host=customHost:1234 cluster_instance_host_pattern=?.customHost` | If the provided connection string is not an IP address or custom domain, the AWS Advanced Python Wrapper will automatically acquire the cluster instance host pattern from the customer-provided connection string. | +| `global_cluster_instance_host_patterns` | String | For Global Databases: Yes

Otherwise: No | This parameter is similar to the `cluster_instance_host_pattern` parameter but it provides a comma-separated list of instance host patterns. This parameter is required for Aurora Global Databases. The list should contain host patterns for each region of the global database.

Each entry uses the format `:` or `::`. A "?" character in the host pattern should be used as a placeholder for the DB instance identifiers.

The parameter is ignored for other types of databases (Aurora Clusters, RDS Clusters, plain RDS databases, etc.).

Example: for an Aurora Global Database with two AWS regions `us-east-2` and `us-west-2`, the parameter value should be set to `us-east-2:?.XYZ1.us-east-2.rds.amazonaws.com,us-west-2:?.XYZ2.us-west-2.rds.amazonaws.com`. Please note that cluster identifiers are different for different AWS regions (`XYZ1` and `XYZ2` in the example above).

The port can also be provided: `us-east-2:?.XYZ1.us-east-2.rds.amazonaws.com:5432,us-west-2:?.XYZ2.us-west-2.rds.amazonaws.com:5432`

For complete Aurora Global Database configuration, see [Aurora Global Databases](../GlobalDatabases.md). | | | `failover_timeout_sec` | Integer | No | Maximum allowed time in seconds to attempt reconnecting to a new writer or reader instance after a cluster failover is initiated. | `300` | | `topology_refresh_ms` | Integer | No | Cluster topology refresh rate in seconds when a cluster is not in failover. It refers to the regular, slow monitoring rate explained above. | `30000` | | `cluster_topology_high_refresh_rate_ms` | Integer | No | Interval of time in milliseconds to wait between attempts to update cluster topology after the writer has come back online following a failover event. It corresponds to the increased monitoring rate described earlier. Usually, the topology monitoring component uses this increased monitoring rate for 30s after a new writer was detected. | `100` | diff --git a/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md b/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md index 1a4a5acfb..23f542bc6 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md @@ -22,7 +22,9 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates > > For more information on configuring AWS credentials, see our [AWS credentials documentation](../AwsCredentials.md). -## How to use the Federated Authentication Plugin with the AWS Advanced Python Wrapper +- This plugin does not create or modify any ADFS or IAM resources, therefore all permissions and policies must be correctly configured before using this plugin. If you plan on using [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/) with this plugin, please see the [Using Federated Authentication with Global Databases](#using-federated-authentication-with-global-databases) section as well. + +## How to use the Federated Authentication Plugin with the AWS Advanced Python Wrapper ### Enabling the Federated Authentication Plugin > [!NOTE]\ @@ -59,3 +61,24 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates ## Sample code [MySQLFederatedAuthentication.py](../../examples/MySQLFederatedAuthentication.py) [PGFederatedAuthentication.py](../../examples/PGFederatedAuthentication.py) + +## Using Federated Authentication with Global Databases + +When using Federated authentication with [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/), the IAM user or role requires the additional `rds:DescribeGlobalClusters` permission. This permission allows the wrapper to resolve the Global Database endpoint to the appropriate regional cluster for IAM token generation. + +Example IAM policy: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "rds-db:connect", + "rds:DescribeGlobalClusters" + ], + "Resource": "*" + } + ] +} +``` diff --git a/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md b/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md index 5402f4339..963381969 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md @@ -49,3 +49,24 @@ IAM database authentication use is limited to certain database engines. For more [PGIamAuthentication.py](../../examples/PGIamAuthentication.py) [MySQLIamAuthentication.py](../../examples/MySQLIamAuthentication.py) + +## Using IAM Authentication with Global Databases + +When using IAM authentication with [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/), the IAM user or role requires the additional `rds:DescribeGlobalClusters` permission. This permission allows the wrapper to resolve the Global Database endpoint to the appropriate regional cluster for IAM token generation. + +Example IAM policy: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "rds-db:connect", + "rds:DescribeGlobalClusters" + ], + "Resource": "*" + } + ] +} +``` diff --git a/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md b/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md index bf586d4fe..27cb1e3a0 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md @@ -55,3 +55,24 @@ In the case of AD FS, the user signs into the AD FS sign in page. This generates ## Sample code [MySQLOktaAuthentication.py](../../examples/MySQLOktaAuthentication.py) [PGOktaAuthentication.py](../../examples/PGOktaAuthentication.py) + +## Using Okta Authentication with Global Databases + +When using Okta authentication with [Amazon Aurora Global Databases](https://aws.amazon.com/rds/aurora/global-database/), the IAM user or role requires the additional `rds:DescribeGlobalClusters` permission. This permission allows the wrapper to resolve the Global Database endpoint to the appropriate regional cluster for IAM token generation. + +Example IAM policy: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "rds-db:connect", + "rds:DescribeGlobalClusters" + ], + "Resource": "*" + } + ] +} +```