The AWS Advanced Ruby Driver Wrapper is complementary to an existing Ruby database driver and aims to extend the functionality of the driver to enable applications to take full advantage of the features of clustered databases such as Amazon Aurora. In other words, the AWS Advanced Ruby Driver Wrapper does not connect directly to any database, but enables support of AWS and Aurora functionalities on top of an underlying Ruby driver of the user's choice. This approach enables service-specific enhancements without requiring users to change their workflow with their existing Ruby drivers and tooling.
The wrapper integrates with ActiveRecord by providing drop-in aws_mysql2 and aws_postgresql adapters that sit on top of the community mysql2 and pg drivers.
Hosting a database cluster in the cloud via Aurora provides users with sets of features and configurations to obtain maximum performance and availability, such as database failover. However, at the moment, most existing drivers do not currently support those functionalities or are not able to entirely take advantage of them.
The main idea behind the AWS Advanced Ruby Driver Wrapper is to add a software layer on top of an existing Ruby driver that would enable all the enhancements brought by Aurora, without requiring users to change their workflow with their databases and existing Ruby drivers.
In an Amazon Aurora database cluster, failover is a mechanism by which Aurora automatically repairs the 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 Ruby Driver Wrapper is designed to understand the situation and coordinate with the cluster in order to provide minimal downtime and allow connections to be very quickly restored in the event of a DB instance failure.
Although Aurora is able to provide maximum availability through the use of failover, existing client drivers do not currently support this functionality. This is partially due to the time required for the DNS of the new primary DB instance to be fully resolved in order to properly direct the connection. The AWS Advanced Ruby Driver Wrapper allows customers to continue using their existing community drivers in addition to having the wrapper fully exploit failover behavior by maintaining a cache of the Aurora cluster topology and each DB instance's role (Aurora Replica or primary DB instance). This topology is provided via a direct query to the Aurora DB, essentially providing a shortcut to bypass the delays caused by DNS resolution. With this knowledge, the wrapper can more closely monitor the Aurora DB cluster status so that a connection to the new primary DB instance can be established as fast as possible.
Built-in support for AWS Identity and Access Management (IAM) authentication eliminates the need to manage database passwords, while AWS Secrets Manager integration provides secure credential management for services that require password-based authentication.
The plugin-based design ensures applications only load the functionality they need, reducing dependencies and overhead. The following plugins are currently available:
| Plugin | Description |
|---|---|
| Failover | Reduces connection recovery time during Aurora/RDS failovers by using cached cluster topology. See Enhanced Failover Plugin. |
| Global Database (GDB) Failover | Adds awareness of Amazon Aurora Global Databases to the failover logic. See Global Database Failover Plugin. |
| IAM Authentication | Connects using short-lived IAM authentication tokens instead of a database password. See IAM Authentication Plugin. |
| AWS Secrets Manager | Retrieves database credentials from AWS Secrets Manager. See AWS Secrets Manager Plugin. |
| Custom Endpoint | Adds awareness of Aurora custom endpoints to topology and host selection. See Custom Endpoint Plugin. |
| Blue/Green Deployment | Adds awareness of Amazon RDS/Aurora Blue/Green deployments to minimize downtime during switchover. See Blue/Green Deployment Plugin. |
| Initial Connection Strategy | Controls how the initial connection to a cluster is established and verified. See Initial Connection Strategy Plugin. |
| KMS Encryption | Transparently encrypts and decrypts individual table columns using data keys held in AWS KMS. See KMS Encryption Plugin. |
Important
iam and secrets_manager are mutually exclusive. Only one authentication plugin may be active at a time. Configuring both will raise a PluginConflictError at connection initialization.
The wrapper design allows developers to continue using their preferred Ruby drivers and existing ActiveRecord code while gaining service-specific enhancements. No application rewrites are required — you only change the adapter name in your database configuration.
Add this line to your application's Gemfile:
gem 'aws_advanced_ruby_driver_wrapper'For MySQL users, also install the underlying driver:
gem 'mysql2'For PostgreSQL users, also install the underlying driver:
gem 'pg'Then execute:
bundle installThe wrapper registers two ActiveRecord adapters — aws_mysql2 and aws_postgresql — that are drop-in replacements for the standard mysql2 and postgresql adapters.
Require the appropriate entry point for your database:
# For MySQL
require 'aws_advanced_ruby_driver_wrapper/mysql'
# For PostgreSQL
require 'aws_advanced_ruby_driver_wrapper/postgresql'Then set the adapter in your database configuration (for example, config/database.yml in a Rails application):
# MySQL
production:
adapter: aws_mysql2
host: my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com
database: mydb
username: admin
password: <password>
# PostgreSQL
production:
adapter: aws_postgresql
host: my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com
database: mydb
username: admin
password: <password>This is a minimal configuration. To add failover tuning, IAM or Secrets Manager authentication, TLS, and other plugins for your deployment, see the documentation, or let an AI assistant build the configuration with you.
If you use an AI assistant (Kiro, Cursor, Claude Code, GitHub Copilot, ChatGPT, Amazon Bedrock, etc.), you can give it the wrapper's configuration assistant skill to help build, review, or troubleshoot your wrapper configuration.
The skill is a single self-contained markdown file, skills/ruby-wrapper-configuration-assistant/SKILL.md. It covers every plugin, parameter, default value, dialect, failover mode, and compatibility constraint, so the AI can answer configuration questions without access to the wrapper source. It follows the Agent Skills format. It is about 51,000 tokens on Claude Opus 5.5 and Sonnet 5.5 (other models count tokens differently), and the AI receives it with every message, so tools that cache prompts handle it most cheaply.
- Download or copy
SKILL.md, or the wholeskills/ruby-wrapper-configuration-assistantfolder. - Add it to your AI tool:
-
Tools that support Agent Skills (Kiro, Cursor, Claude Code, GitHub Copilot in VS Code, and others): copy the
ruby-wrapper-configuration-assistantfolder (or create a folder with that name and saveSKILL.mdin it) into one of the tool's skills directories. The folder name must match thenamefield at the top of the file (ruby-wrapper-configuration-assistant), as the Agent Skills format requires; a tool may not load the skill if they differ.Tool Project skills directory User skills directory Kiro .kiro/skills/~/.kiro/skills/Cursor .cursor/skills/,.agents/skills/, or.claude/skills/~/.cursor/skills/,~/.agents/skills/, or~/.claude/skills/Claude Code .claude/skills/~/.claude/skills/GitHub Copilot in VS Code .github/skills/,.agents/skills/, or.claude/skills/~/.copilot/skills/,~/.agents/skills/, or~/.claude/skills/For example, to add the skill to a project for Claude Code:
mkdir -p .claude/skills/ruby-wrapper-configuration-assistant curl -fsSL -o .claude/skills/ruby-wrapper-configuration-assistant/SKILL.md \ https://raw.githubusercontent.com/aws/aws-advanced-ruby-driver-wrapper/main/skills/ruby-wrapper-configuration-assistant/SKILL.md
-
Claude Projects: upload it as a project knowledge document.
-
ChatGPT custom GPT: upload it as a knowledge file.
-
Amazon Bedrock: send the file as the system prompt of your
InvokeModelorConverserequest. Avoid attaching it to a Bedrock knowledge base: a knowledge base passes the model only the passages that match each question, so the model misses the instructions and cross-references the skill depends on. -
Plain chat (ChatGPT, Claude, Gemini): paste it at the start of a new conversation, then ask your question.
-
- Ask the AI for help. It will interview you when it needs more details, or give you a configuration straight away if you ask it to skip the interview.
The simplest way to start:
Help me configure the AWS Advanced Ruby Driver Wrapper for my Rails app.
Skip the interview when you already know what you want:
Give me a default config/database.yml for Rails on Aurora PostgreSQL with failover and IAM authentication.
Review an existing configuration:
Review this database.yml entry and tell me what to change:
<paste your database.yml entry, or the Ruby code that opens the connection>
Diagnose a configuration error:
My Rails app on aws_postgresql fails at startup with "The failover plugin is not compatible with RDS Proxy endpoints".
What's wrong with my database.yml?
The skill targets wrapper version 1.0.1 and later. If it doesn't know something, it says so and points you to the Ruby wrapper documentation.
Technical documentation regarding the functionality of the AWS Advanced Ruby Driver Wrapper is published at the AWS Advanced Wrapper documentation site. Since the wrapper requires an underlying Ruby driver, please refer to the individual driver's documentation for driver-specific information.
| Topic | Documentation |
|---|---|
| Overview | Overview |
| Failover Plugin | Enhanced Failover Plugin |
| Global Database Failover Plugin | Global Database Failover Plugin |
| AWS IAM Authentication Plugin | IAM Authentication Plugin |
| AWS Secrets Manager Plugin | AWS Secrets Manager Plugin |
| Custom Endpoint Plugin | Custom Endpoint Plugin |
| Blue/Green Deployment Plugin | Blue/Green Deployment Plugin |
| Initial Connection Strategy Plugin | Initial Connection Strategy Plugin |
| KMS Encryption Plugin | KMS Encryption Plugin |
| Configuring AWS Credentials | AWS Credentials |
| Configuring TLS/SSL | Configuring TLS/SSL |
| Plugin Compatibility | Plugin Compatibility |
| Running the integration tests | Integration Tests |
Support for Blue/Green deployments using the wrapper requires specific metadata tables. Please refer to the plugin documentation for the supported database engine versions.
If you encounter a bug with the AWS Advanced Ruby Driver Wrapper, we would like to hear about it. Please search the existing issues to see if others are also experiencing the issue before reporting the problem in a new issue. GitHub issues are intended for bug reports and feature requests.
When opening a new issue, please fill in all required fields in the issue template to help expedite the investigation process.
For all other questions, please use GitHub discussions.
- Set up your environment by following the directions in the Contributing Guide.
- To contribute, first make a fork of this project.
- Make any changes on your fork. Make sure you are aware of the requirements for the project.
- Create a pull request from your fork.
- Pull requests need to be approved and merged by maintainers into the main branch.
Note: Before making a pull request, run all tests and verify everything is passing.
The AWS Advanced Ruby Driver Wrapper is part of a broader family of AWS "wrapper" drivers that bring the same advanced functionality, such as failover support and IAM authentication, to other languages and database connectivity standards. If you are working outside of Ruby, you may find one of the following drivers useful:
| Driver | Repository |
|---|---|
| AWS Advanced JDBC Wrapper | https://github.com/aws/aws-advanced-jdbc-wrapper |
| AWS Advanced Python Wrapper | https://github.com/aws/aws-advanced-python-wrapper |
| AWS Advanced NodeJS Wrapper | https://github.com/aws/aws-advanced-nodejs-wrapper |
| AWS Advanced Go Wrapper | https://github.com/aws/aws-advanced-go-wrapper |
| AWS Advanced .NET Wrapper | https://github.com/aws/aws-advanced-dotnet-data-provider-wrapper |
| AWS Advanced ODBC Wrapper | https://github.com/aws/aws-advanced-odbc-wrapper |
This software is released under the Apache 2.0 license.