diff --git a/README.md b/README.md index 49983bf7..fd0c3215 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,6 @@ 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 a68c8f45..1bdf474f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,6 @@ - [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/using-the-python-wrapper/DatabaseDialects.md b/docs/using-the-python-wrapper/DatabaseDialects.md index 6ab20af0..ec77928f 100644 --- a/docs/using-the-python-wrapper/DatabaseDialects.md +++ b/docs/using-the-python-wrapper/DatabaseDialects.md @@ -23,12 +23,10 @@ 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 deleted file mode 100644 index 90e4a7d2..00000000 --- a/docs/using-the-python-wrapper/GlobalDatabases.md +++ /dev/null @@ -1,129 +0,0 @@ -# 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 fc47f602..83bfb067 100644 --- a/docs/using-the-python-wrapper/UsingThePythonWrapper.md +++ b/docs/using-the-python-wrapper/UsingThePythonWrapper.md @@ -28,8 +28,7 @@ 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 | 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 | +| 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 | | 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 1b7e6d6c..e3ae6bd8 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheFailover2Plugin.md @@ -58,7 +58,6 @@ 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 23f542bc..edc4f458 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheFederatedAuthenticationPlugin.md @@ -22,8 +22,6 @@ 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). -- 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 @@ -61,24 +59,3 @@ 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 96338196..5402f433 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheIamAuthenticationPlugin.md @@ -49,24 +49,3 @@ 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 27cb1e3a..bf586d4f 100644 --- a/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md +++ b/docs/using-the-python-wrapper/using-plugins/UsingTheOktaAuthenticationPlugin.md @@ -55,24 +55,3 @@ 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": "*" - } - ] -} -```