AWS Ruby Driver Wrapper for Rails: reconnection is not transaction replay

Separate connection recovery from transaction recovery

AWS announced general availability of Advanced Ruby Driver Wrapper on October 5, 2026, for Amazon RDS and Aurora PostgreSQL- and MySQL-compatible databases. It adds cluster features on top of pg or mysql2. It neither replaces the underlying driver nor provides a universal adapter for every Ruby database.

Failover reconnects to another instance when the primary becomes unavailable. The wrapper can replace the physical connection while preserving the connection object held by your application. That does not mean the last statement has been replayed, or that an open transaction is known to have committed or rolled back.

The current overview requires Ruby 3.3 or later. Its tested combinations include ActiveRecord 7.2, 8.0 and 8.1, pg 1.6.3 or later, and mysql2 0.5.7 or later. Check your own combination first; this tested coverage does not establish compatibility with every version.

Keep the underlying driver and check the default plugins

Add gem 'aws_advanced_ruby_driver_wrapper' to the Gemfile and keep gem 'pg' or gem 'mysql2' for your database, then run bundle install in your own controlled environment. The current overview says Bundler loads the wrapper; a plain Ruby script can use require 'aws_advanced_ruby_driver_wrapper'.

In config/database.yml, replace postgresql with aws_postgresql, or mysql2 with aws_mysql2, and point host at the appropriate cluster endpoint. The adapters let you retain existing ActiveRecord calls and its connection pool. You must still review exception handling and transaction retries separately.

When wrapper_plugins is absent, the wrapper loads failover and initial_connection. Setting it replaces the default list rather than extending it. A list containing only iam omits those defaults; explicitly include failover,initial_connection,iam if you intend to retain them.

More plugins are not automatically better. iam and secrets_manager cannot be enabled together. A single connection also cannot use both failover and gdb_failover. Either conflict raises PluginConflictError during connection initialization, so choose a combination that matches your authentication method and database topology.

Use the three errors to decide what to reuse or retry

FailoverSuccessError means failover succeeded outside a transaction and the connection is valid and reusable. Restore the session state your application requires before considering a replay of the interrupted statement. Do not discard the recovered connection simply because this error was raised.

TransactionStateUnknownError means a transaction was open during failover and the wrapper cannot determine whether it completed. The connection is reusable, but the outcome is unknown. For non-idempotent operations such as charging a payment or writing an order, confirm the result before deciding how to restart the transaction and replay its statements.

FailoverFailedError means the attempt did not reconnect to an available instance and the original connection is invalid. Wait for the server to become available before reconnecting; do not treat this as a successful recovery. Through ActiveRecord, this error is translated into ActiveRecord::ConnectionFailed.

The other two errors are not translated into generic ActiveRecord exceptions. Your application receives the original classes under AwsAdvancedRubyDriverWrapper::Errors. Handling only ActiveRecord::ConnectionFailed misses both successful reconnection and the unknown-transaction-outcome path.

Keep the pool working and restore the session state you need

After a successful failover, the ActiveRecord adapter runs configure_connection again and reuses the pooled connection in place. Do not additionally call disconnect! or discard that object. After a failed failover, the adapter marks the connection as broken and leaves the pool to handle it on the next checkout.

Session variables declared through the adapter's variables: option are reapplied by configure_connection. The prepared-statement cache is cleared so statements are prepared again on their next use. Your application must still recreate custom state such as temporary tables and advisory locks; it cannot assume that every part of a session transfers.

Consider a hypothetical, unexecuted example: an order write encounters TransactionStateUnknownError inside a transaction. The application first checks the business record to determine the original write's outcome, then applies its own idempotency rules before deciding whether to submit it again. A recovered connection alone is not a reason to repeat the write.

Complete the topology settings for custom hosts and multiple clusters

If you connect through an IP address, CNAME or custom domain, the wrapper may not be able to derive instance endpoints from host. Set cluster_instance_host_pattern with ? as the instance-identifier placeholder. A CNAME or custom domain also requires a cluster identifier.

Give different clusters different cluster_id values when one application uses several clusters. Connections sharing an identifier share a topology monitor and cache, so unrelated clusters must not accidentally use the same identity. Recognizable RDS endpoints do not remove this multi-cluster check.

The default failover_timeout_sec is 300.0 seconds: the maximum allowed reconnection time after failover begins. It is not a promise that the database will recover within 300 seconds. The monitor queries topology and searches for suitable instances, while actual recovery still depends on database state and connection conditions.

Review support boundaries separately from application responsibilities

The announcement also describes RDS Blue/Green and Aurora Global Database switchover capabilities. Use the corresponding plugins and consult their own documentation. The repository explicitly says Blue/Green requires specific metadata tables and supported engine versions; the GA announcement alone does not establish support for every deployment.

The wrapper is open source under Apache 2.0; that does not make related AWS services free. The announcement, overview and failover pages used here provide no universal region list, additional-service pricing or recovery-time commitment. Confirm service eligibility and billing for the AWS products you actually use.

A useful integration review has four parts: check Ruby, ActiveRecord and the underlying driver; confirm the adapter, endpoint and plugin list; make the application distinguish all three errors; and define transaction confirmation, retries and session restoration. Replacing the adapter does not remove the last two responsibilities.