failover-plugin.md

Failover Plugin for the AWS Advanced ODBC Wrapper

Failover Process

In an Amazon Aurora database (DB) cluster, failover is a mechanism by which Aurora automatically repairs the DB cluster status when a primary DB instance becomes unavailable. It achieves this goal by electing an Aurora Replica to become the new primary DB instance, so that the DB cluster can provide maximum availability to a primary read-write DB instance. The AWS Advanced ODBC Wrapper implements failover support to coordinate with this behavior to provide minimal downtime in the event of a DB instance failure. To learn more about Aurora cluster's failover feature see the Amazon RDS documentation.

The figure above provides a simplified overview of how the AWS Advanced ODBC Wrapper handles an Aurora failover encounter. Starting at the top of the diagram, an application using the driver sends a request to get a logical connection to an Aurora database.

In this example, the application requests a connection using the Aurora DB cluster endpoint and is returned a logical connection that is physically connected to the primary DB instance in the DB cluster, DB instance C. By design, details about which specific DB instance the physical connection is connected to have been abstracted away.

Over the course of the application's lifetime, it executes various statements against the logical connection. If DB instance C is stable and active, these statements succeed and the application continues as normal. If DB instance C experiences a failure, Aurora will initiate failover to promote a new primary DB instance. At the same time, the AWS Advanced ODBC Wrapper will intercept the related communication exception and kick off its own internal failover process.

If the primary DB instance has failed, the driver will use its internal topology cache to temporarily connect to an active Aurora Replica. This Aurora Replica will be periodically queried for the DB cluster topology until the new primary DB instance is identified (DB instance A or B in this case).

At this point, the driver will connect to the new primary DB instance and return control to the application to allow the user to reconfigure the session state as needed. Although the DNS endpoint for the DB cluster might not yet resolve to the new primary DB instance, the driver has already discovered this new DB instance during its failover process, and will be directly connected to it when the application continues executing statements. In this way the driver provides a faster way to reconnect to a newly promoted DB instance, thus increasing the availability of the DB cluster.

Connection String / DSN Configuration for Failover Plugin Support

Field	Connection Option Key	Value	Default Value	Sample Value
Enable Cluster Failover	ENABLE_CLUSTER_FAILOVER	Set to 1 to enable the fast failover behaviour offered by the AWS Advanced ODBC Wrapper.	0	1
Failover Mode	FAILOVER_MODE	Defines a mode for failover process. The failover process may prioritize nodes with different roles and connect to them. Possible values: - STRICT_WRITER - Failover process tries to detect the new writer when it changes. If it cannot detect this writer within the set FAILOVER_TIMEOUT_MS value, the driver raises an error. - READER_OR_WRITER - During failover, the driver tries to connect to any available/accessible reader node. If no reader is available, the driver will connect to a writer node. This logic mimics the logic of the Aurora read-only cluster endpoint. - STRICT_READER - During failover, the driver tries to connect to any available reader node. If no reader is available, the driver raises an error. 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.	Default value depends on the connection url. For Aurora read-only cluster endpoints, it's set to READER_OR_WRITER. Otherwise, it's STRICT_WRITER.	STRICT_READER
Host Pattern	HOST_PATTERN	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. Example: ?.my-domain.com, any-subdomain.?.my-domain.com:9999 Usecase Example: If your cluster instance endpoint follows this pattern:instanceIdentifier1.customHost, instanceIdentifier2.customHost, etc. and you want your initial connection to be to customHost:1234, then your connection string should look like this: SERVER=customHost;PORT=1234;DATABASE=test;HOST_PATTERN=?.customHost If the provided connection string is not an IP address or custom domain, the driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. For more details, refer to Driver Behaviour During Failover For Different Connection URLs.	nil	?.my-domain.com
Cluster Identifier	CLUSTER_ID	A unique identifier for the cluster. Connections with the same cluster ID share a cluster topology cache. This connection parameter is not required and thus should only be set if desired.	The cluster ID	my-cluster-id
Reader Host Selector Strategy	HOST_SELECTOR_STRATEGY	Strategy used to select a reader node during failover. For more information on the available reader selection strategies. Currently supported strategies are: RANDOM_HOST, ROUND_ROBIN, HIGHEST_WEIGHT.	RANDOM	ROUND_ROBIN
Topology Refresh Rate	TOPOLOGY_REFRESH_RATE_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.	30000	10000
Topology High Refresh Rate	TOPOLOGY_HIGH_REFRESH_RATE_MS	Interval of time in milliseconds to wait between attempts to reconnect to a failed writer during a writer failover process.	10000	1000
Ignore Topology Refresh Request	IGNORE_TOPOLOGY_REQUEST_MS	Cluster topology refresh grace period in millisecond. Requests to update topology will be ignored after establishing an initial connection for the specified milliseconds.	30000	60000
Failover Timeout	FAILOVER_TIMEOUT_MS	Maximum allowed time in milliseconds to attempt reconnecting to a new writer or reader instance after a cluster failover is initiated.	30000	60000

Wrapper Behaviour During Failover For Different Connection URLs

Host Pattern

When connecting to Aurora clusters, this 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 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 HostPattern should be set to ?.customHost, making the connection string SERVER=customHost;PORT=1234;DATABASE=test;HOST_PATTERN=?.customHost. Refer to Wrapper Behaviour During Failover For Different Connection URLs for more examples.

Failover Exception Codes

08S01 - Failover Failed

When the wrapper returns an error code 08S01, the original connection failed, and the wrapper tried to failover to a new instance, but was not able 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.

08S02 - Failover Succeeded

When the wrapper returns an error code 08S02, the original connection failed while autocommit was set to true, and the wrapper successfully failed over to another available instance in the cluster. However, any session state configuration of the initial connection is now lost. In this scenario, you should:

1. Reconfigure and reuse the original connection (the reconfigured session state will be the same as the original connection).
2. Repeat the query that was executed when the connection failed and continue work as desired.

08007 - Transaction Unknown

The original connection failed while the wrapper was in a transaction. Please restart the transaction and reset any session states.

Failover Usage Advisories

Sample Code

Aurora PostgreSQL Failover Example