docs: add documentation around plugins, endpoint and database type compatibility #1267
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Plugins compatibility | ||
|
|
||
| The AWS Advanced Python Wrapper uses plugins to execute database method calls. You can think of a plugin as an extensible code module that adds additional logic around driver method calls. Plugins are designed with the intention of being compatible with each other; however, there are logical constraints related to database type or database features that can make plugins inefficient in certain configurations. | ||
|
|
||
| For example, RDS Single-AZ Instance deployments do not support failover, so the `failover` and `failover_v2` plugins are marked as incompatible with that deployment. If either of these plugins is included in the driver configuration, there will be no added value. However, these unnecessary plugins will function without errors and will simply consume additional resources. | ||
|
|
||
| The following matrices help verify plugin compatibility with other plugins and with various database types. Some plugins are sensitive to the database URL provided in the connection string, and this is also presented below. | ||
|
|
||
| We encourage users to verify their configurations and ensure that their configuration contains no incompatible components. | ||
|
|
||
| - [Database type compatibility](./CompatibilityDatabaseTypes.md) | ||
| - [Database URL type compatibility](./CompatibilityEndpoints.md) | ||
| - [Cross plugin compatibility](./PluginChainCompatibility.md) — the plugin-vs-plugin matrix plus driver/runtime constraints, plugin ordering, and canonical chains | ||
|
|
||
| ## Universally Compatible Plugins | ||
|
|
||
| The following plugins operate independently of connection management and are compatible with all plugins, database types, and endpoint types: | ||
|
|
||
| | Plugin | Description | | ||
| |----------------|----------------------------------------------------| | ||
| | [dev](../using-plugins/UsingTheDeveloperPlugin.md) | Developer utility plugin for debugging and diagnostics. | | ||
| | `connect_time` | Logs the time taken to establish a connection. | | ||
| | `execute_time` | Logs the time taken to execute any driver method. | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # Database type compatibility | ||
|
|
||
| This document is part of the [Compatibility Guide](./Compatibility.md) and explains plugin compatibility with various database types and deployments. Some plugins require specific metadata from particular database types to function properly. | ||
|
|
||
| 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. | ||
|
|
||
| For Aurora Global Database configuration details, see [Aurora Global Databases](../GlobalDatabases.md). | ||
|
|
||
| Legend: ✅ compatible | ❌ incompatible / no added value | ||
|
|
||
| | Plugin code / Database type | Aurora Global Database <br>(MySQL and PG) | Aurora Cluster <br>(MySQL and PG) | RDS Multi-AZ DB Cluster (3 instances) <br>(MySQL and PG) | | ||
| |---|:---:|:---:|:---:| | ||
| | [custom_endpoint](../using-plugins/UsingTheCustomEndpointPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [host_monitoring](../using-plugins/UsingTheHostMonitoringPlugin.md) (EFM v1) | ✅ | ✅ | ✅ | | ||
| | [host_monitoring_v2](../using-plugins/UsingTheHostMonitoringPlugin.md) (EFM v2) | ✅ | ✅ | ✅ | | ||
| | [failover](../using-plugins/UsingTheFailoverPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [failover_v2](../using-plugins/UsingTheFailover2Plugin.md) | ✅ | ✅ | ✅ | | ||
| | [gdb_failover](../using-plugins/UsingTheGdbFailoverPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [iam](../using-plugins/UsingTheIamAuthenticationPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [aws_secrets_manager](../using-plugins/UsingTheAwsSecretsManagerPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [federated_auth](../using-plugins/UsingTheFederatedAuthenticationPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [okta](../using-plugins/UsingTheOktaAuthenticationPlugin.md) | ✅ | ✅ | ✅ | | ||
| | stale_dns | ✅ | ✅ | ✅ | | ||
| | [read_write_splitting](../using-plugins/UsingTheReadWriteSplittingPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [srw](../using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [gdb_rw](../using-plugins/UsingTheGdbReadWriteSplittingPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [aurora_connection_tracker](../using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | ✅ | ✅ | ✅ | | ||
| | connect_time | ✅ | ✅ | ✅ | | ||
| | [fastest_response_strategy](../using-plugins/UsingTheFastestResponseStrategyPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [initial_connection](../using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md) | ✅ | ✅ | ✅ | | ||
| | [limitless](../using-plugins/UsingTheLimitlessPlugin.md) | ❌ | ✅ (PostgreSQL only) | ✅ | | ||
|
Contributor
There was a problem hiding this comment. The second check mark should say PG only as well |
||
| | [bg](../using-plugins/UsingTheBlueGreenPlugin.md) | ❌ | ✅ | ❌ | | ||
|
|
||
| <br> | ||
|
|
||
| | Plugin code / Database type | RDS Multi-AZ DB Instance (2 instances) <br>(MySQL and PG) | RDS Single-AZ Instance (1 instance) <br>(MySQL and PG) | Community Database <br>(MySQL and PG) | | ||
| |---|:---:|:---:|:---:| | ||
| | [custom_endpoint](../using-plugins/UsingTheCustomEndpointPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [host_monitoring](../using-plugins/UsingTheHostMonitoringPlugin.md) (EFM v1) | ✅ | ✅ | ✅ | | ||
| | [host_monitoring_v2](../using-plugins/UsingTheHostMonitoringPlugin.md) (EFM v2) | ✅ | ✅ | ✅ | | ||
| | [failover](../using-plugins/UsingTheFailoverPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [failover_v2](../using-plugins/UsingTheFailover2Plugin.md) | ❌ | ❌ | ❌ | | ||
| | [gdb_failover](../using-plugins/UsingTheGdbFailoverPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [iam](../using-plugins/UsingTheIamAuthenticationPlugin.md) | ✅ | ✅ | ❌ | | ||
| | [aws_secrets_manager](../using-plugins/UsingTheAwsSecretsManagerPlugin.md) | ✅ | ✅ | ❌ | | ||
| | [federated_auth](../using-plugins/UsingTheFederatedAuthenticationPlugin.md) | ✅ | ✅ | ❌ | | ||
| | [okta](../using-plugins/UsingTheOktaAuthenticationPlugin.md) | ✅ | ✅ | ❌ | | ||
| | stale_dns | ❌ | ❌ | ❌ | | ||
| | [read_write_splitting](../using-plugins/UsingTheReadWriteSplittingPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [srw](../using-plugins/UsingTheSimpleReadWriteSplittingPlugin.md) | ✅ | ❌ | ✅ | | ||
| | [gdb_rw](../using-plugins/UsingTheGdbReadWriteSplittingPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [aurora_connection_tracker](../using-plugins/UsingTheAuroraConnectionTrackerPlugin.md) | ❌ | ❌ | ❌ | | ||
| | connect_time | ✅ | ✅ | ✅ | | ||
| | [fastest_response_strategy](../using-plugins/UsingTheFastestResponseStrategyPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [initial_connection](../using-plugins/UsingTheAuroraInitialConnectionStrategyPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [limitless](../using-plugins/UsingTheLimitlessPlugin.md) | ❌ | ❌ | ❌ | | ||
| | [bg](../using-plugins/UsingTheBlueGreenPlugin.md) | ✅ | ✅ | ❌ | | ||
|
|
||
| > The `connect_time`, `execute_time`, and [`dev`](../using-plugins/UsingTheDeveloperPlugin.md) plugins are compatible with every database type (see [Universally Compatible Plugins](./Compatibility.md#universally-compatible-plugins)). | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might help if it looks the same as the others