Skip to content

docs: add enableFailoverStrictReader parameter to the documentation #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 15, 2023
Merged

docs: add enableFailoverStrictReader parameter to the documentation #457

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,16 +219,16 @@ There are many different types of URLs that can connect to an Aurora DB cluster;
Note: The connection string follows standard URL parameters. In order to add parameters to the connection string, simply add `?` and then the `parameter_name=value` pair at the end of the connection string. You may add multiple parameters by separating the parameter name and value set (`parameter_name=value`) with the `&` symbol. For example, to add 2 parameters simply add `?param_name=value&param_2=value2` at the end of the connection string.


| URL Type | Example | Required Parameters | Driver Behavior |
|-----------------------------------------------|--------------------------------------------------------------------------------------|:----------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Cluster Endpoint | `jdbc:mysql:aws://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* primary DB instance<br/>*Failover behavior:* connect to the new primary DB instance |
| Read-Only Cluster Endpoint | `jdbc:mysql:aws://db-identifier.cluster-ro-XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* any Aurora Replica<br/>*Failover behavior:* prioritize connecting to any active Aurora Replica but might connect to the primary DB instance if it provides a faster connection |
| Instance Endpoint | `jdbc:mysql:aws://instance-1.XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* the instance specified (DB instance 1)<br/>*Failover behavior:* connect to the primary DB instance |
| RDS Custom Cluster | `jdbc:mysql:aws://db-identifier.cluster-custom-XYZ.us-east-2.rds.amazonaws.com:3306` | None | The driver does not support custom clusters yet. *Initial connection:* the primary instance in the cluster<br/>*Failover behavior:* connect to the primary DB instance |
| IP Address | `jdbc:mysql:aws://10.10.10.10:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |
| Custom Domain | `jdbc:mysql:aws://my-custom-domain.com:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |
| Non-Aurora Endpoint | `jdbc:mysql:aws://localhost:3306` | None | A regular JDBC connection will be returned - no failover functionality |
| Aurora Endpoint<br/>(through a custom tunnel) | `jdbc:mysql:aws://localhost:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |
| URL Type | Example | Required Parameters | Driver Behavior |
|-----------------------------------------------|--------------------------------------------------------------------------------------|:----------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Cluster Endpoint | `jdbc:mysql:aws://db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* primary DB instance<br/>*Failover behavior:* connect to the new primary DB instance |
| Read-Only Cluster Endpoint | `jdbc:mysql:aws://db-identifier.cluster-ro-XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* any Aurora Replica<br/>*Failover behavior:* prioritize connecting to any active Aurora Replica but might connect to the primary DB instance if it provides a connection first |
| Instance Endpoint | `jdbc:mysql:aws://instance-1.XYZ.us-east-2.rds.amazonaws.com:3306` | None | *Initial connection:* the instance specified (DB instance 1)<br/>*Failover behavior:* connect to the primary DB instance |
| RDS Custom Cluster | `jdbc:mysql:aws://db-identifier.cluster-custom-XYZ.us-east-2.rds.amazonaws.com:3306` | None | The driver does not support custom clusters yet. *Initial connection:* the primary instance in the cluster<br/>*Failover behavior:* connect to the primary DB instance |
| IP Address | `jdbc:mysql:aws://10.10.10.10:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |
| Custom Domain | `jdbc:mysql:aws://my-custom-domain.com:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |
| Non-Aurora Endpoint | `jdbc:mysql:aws://localhost:3306` | None | A regular JDBC connection will be returned - no failover functionality |
| Aurora Endpoint<br/>(through a custom tunnel) | `jdbc:mysql:aws://localhost:3306` | `clusterInstanceHostPattern` | *Initial connection:* the DB instance specified<br/>*Failover behavior:* connect to the primary DB instance |

Information about the `clusterInstanceHostPattern` parameter is provided in the section below.

Expand Down Expand Up @@ -304,6 +304,7 @@ In addition to [the parameters that you can configure for the MySQL Connector/J
| `gatherMetricsPerInstance` | Boolean | No | Set to true to gather additional performance metrics per instance as well as cluster. Set to false to only gather performance metrics per cluster. <br><br>To print collected metrics at instance level, call `IClusterAwareMetricsReporter.reportMetrics(String connUrl, Log log, true)`. | `false` |
| `allowXmlUnsafeExternalEntity` | Boolean | No | Set to true if you would like to use XML inputs that refer to external entities. WARNING: Setting this to true is unsafe since your system to be prone to XXE attacks. | `false` |
| `keepSessionStateOnFailover` | Boolean | No | This parameter will allow connections to retain the session state after failover. When `keepSessionStateOnFailover` is set to false, connections will need to be reconfigured as seen in the examples [here](#08007---Transaction-Resolution-Unknown). When this parameter is true, the `autocommit`, `sessionMaxRows` and `transactionIsolation` values will be kept. This parameter is only necessary when the session state must be retained and the connection cannot be manually reconfigured by the user. <br><br> **Please note:** this parameter will not be able to fully restore the connection session state, as it will only save the `autocommit`, `sessionMaxRows` and `transactionIsolation` values. | `false` |
| `enableFailoverStrictReader` | Boolean | No | Set to true to only allow failover to reader nodes during the reader failover process. If enabled, reader failover to a writer node will only be allowed for single-node clusters. This logic mimics the logic of the Aurora read-only cluster endpoint. | `false` |

### Failover Exception Codes
#### 08001 - Unable to Establish SQL Connection
Expand Down