Skip to content

chore: add a table for exception codes #46

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 2 commits into from
Aug 11, 2022
Merged

chore: add a table for exception codes #46

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
14d74d4
chore: add a table for exception codes
karenc-bq Aug 10, 2022
9e0286a
chore: address code review
karenc-bq Aug 11, 2022
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
7 changes: 7 additions & 0 deletions docs/using-the-jdbc-wrapper/using-plugins/UsingTheFailoverPlugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,13 @@ In addition to the parameters that you can configure for the underlying driver,
When connecting to Aurora clusters, the [`clusterInstanceHostPattern`](#failover-parameters) parameter is required when the connection string does not provide enough information about the database cluster domain name. If the Aurora cluster endpoint is used directly, the JDBC Wrapper will recognize the standard Aurora domain name and can re-build a proper Aurora instance name when needed. In cases where the connection string uses an IP address, a custom domain name or localhost, the wrapper won't know how to build a proper domain name for a database instance endpoint. For example, if a custom domain was being used and the cluster instance endpoints followed a pattern of `instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc., the wrapper would need to know how to construct the instance endpoints using the specified custom domain. Because there isn't enough information from the custom domain alone to create the instance endpoints, the `clusterInstanceHostPattern` should be set to `?.customHost`, making the connection string `jdbc:aws-wrapper:postgresql://customHost:1234/test?clusterInstanceHostPattern=?.customHost`. Refer to [this diagram](../../images/failover_behavior.png) on JDBC Wrapper behavior during failover for different connection URLs for more details and examples.

## Failover Exception Codes

| Exceptions | Is the connection valid? | Can the connection be reused? | Has the session state changed? | Does the session need to be reconfigured? | Does the last statement need to be re-executed? | Does the transaction need to be restarted? |
| ------------------------------------------ | ------------------------ | ----------------------------- | ------------------------------ | ----------------------------------------- | ----------------------------------------------- | ------------------------------------------ |
| 08001 - Unable to Establish SQL Connection | No | No | N/A | N/A | Yes | Yes |
| 08S02 - Communication Link | Yes | Yes | Yes | Yes | Yes | N/A |
| 08007 - Transaction Resolution Unknown | Yes | Yes | Yes | Yes | Yes | Yes |

### 08001 - Unable to Establish SQL Connection
When the JDBC Wrapper throws a SQLException with code ```08001```, the original connection has failed, and the JDBC Wrapper tried to failover to a new instance, but was unable to. There are various reasons this may happen: no nodes were available, a network failure occurred, and so on. In this scenario, please wait until the server is up or other problems are solved. (Exception will be thrown.)

Expand Down