# Amazon Web Services (AWS) Advanced Ruby Driver Wrapper
[](LICENSE)
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](https://guides.rubyonrails.org/active_record_basics.html) by providing drop-in `aws_mysql2`, `aws_trilogy` and `aws_postgresql` adapters that sit on top of the community [`mysql2`](https://rubygems.org/gems/mysql2), [`trilogy`](https://rubygems.org/gems/trilogy) and [`pg`](https://rubygems.org/gems/pg) drivers.
## About the Wrapper
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.
### What is Failover?
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.
### Benefits of the AWS Advanced Ruby Driver Wrapper
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.
### Seamless AWS Authentication Service Integration
Built-in support for [AWS Identity and Access Management (IAM)](https://aws.amazon.com/iam/) authentication eliminates the need to manage database passwords, while [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) integration provides secure credential management for services that require password-based authentication.
### Modular Plugin Architecture
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](https://aws.github.io/aws-advanced-wrapper-docs/ruby/enhanced-failover). |
| Global Database (GDB) Failover | Adds awareness of Amazon Aurora Global Databases to the failover logic. See [Global Database Failover Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/gdb-failover). |
| IAM Authentication | Connects using short-lived IAM authentication tokens instead of a database password. See [IAM Authentication Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/iam-authentication). |
| AWS Secrets Manager | Retrieves database credentials from AWS Secrets Manager. See [AWS Secrets Manager Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/aws-secrets-manager). |
| Custom Endpoint | Adds awareness of Aurora custom endpoints to topology and host selection. See [Custom Endpoint Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/custom-endpoint). |
| Blue/Green Deployment | Adds awareness of Amazon RDS/Aurora Blue/Green deployments to minimize downtime during switchover. See [Blue/Green Deployment Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/blue-green). |
| Initial Connection Strategy | Controls how the initial connection to a cluster is established and verified. See [Initial Connection Strategy Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/initial-connection-strategy). |
| KMS Encryption | Transparently encrypts and decrypts individual table columns using data keys held in AWS KMS. See [KMS Encryption Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/kms-encryption). |
> [!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.
### Preserve Existing Workflows
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.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'aws_advanced_ruby_driver_wrapper'
```
For MySQL users, also install one of the underlying drivers:
```ruby
gem 'mysql2'
# or
gem 'trilogy'
```
For PostgreSQL users, also install the underlying driver:
```ruby
gem 'pg'
```
Then execute:
```bash
bundle install
```
## Getting Started
The wrapper registers three ActiveRecord adapters — `aws_mysql2`, `aws_trilogy` and `aws_postgresql` — that are drop-in replacements for the standard `mysql2`, `trilogy` and `postgresql` adapters.
Require the appropriate entry point for your database:
```ruby
# For MySQL with mysql2
require 'aws_advanced_ruby_driver_wrapper/mysql'
# For MySQL with trilogy
require 'aws_advanced_ruby_driver_wrapper/trilogy'
# 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):
```yaml
# MySQL (use aws_trilogy with the trilogy driver)
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](#documentation), or [let an AI assistant build the configuration with you](#configuring-the-wrapper-with-ai-tools).
### Configuring the Wrapper with AI Tools
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`](./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](https://agentskills.io) format. It is about 65,000 tokens on Claude Opus 5.5 and Sonnet 5.5 (other models count tokens differently). How much of that you pay for depends on how you add it:
- **Tools that support Agent Skills** load only the skill's name and description (about 100 tokens) until a request needs the skill. They then load the full file, and it stays in context for the rest of that conversation.
- **A system prompt, or a file pasted into a chat,** sends the full file with every message.
Once the full file is in context, it is sent again with each message, so tools that cache prompts handle it most cheaply.
#### Quick start
1. Download or copy [`SKILL.md`](https://github.com/aws/aws-advanced-ruby-driver-wrapper/blob/v1.1.0/skills/ruby-wrapper-configuration-assistant/SKILL.md) from the latest release, or the whole `skills/ruby-wrapper-configuration-assistant` folder. The copy on `main` can describe changes that aren't released yet; it marks them `[Unreleased]`, and the AI won't recommend them for a released gem version.
2. 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-assistant` folder (or create a folder with that name and save `SKILL.md` in it) into one of the tool's skills directories. The folder name must match the `name` field 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:
```bash
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/v1.1.0/skills/ruby-wrapper-configuration-assistant/SKILL.md
```
- **Claude Projects**: upload it as a project knowledge document. Claude reads project knowledge in full while it fits in the context window, but when a project's knowledge approaches that limit, Claude switches to searching it for passages that match each question, so the model may miss the instructions and cross-references the skill depends on. Keep the project's other knowledge small, or use a separate project.
- **ChatGPT custom GPT**: a custom GPT searches its knowledge files and passes the model only the passages that match each question, so the model may miss the instructions and cross-references the skill depends on. Paste the file into a plain chat instead (below).
- **Amazon Bedrock**: send the file as the system prompt of your `InvokeModel` or `Converse` request. 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. Start a new conversation for each new question: in a long conversation the pasted skill can be pushed out of the model's context, and ChatGPT drops the oldest messages first. In ChatGPT, the file is about 40,000 tokens, which is more than the Free plan's context window and leaves little room on the Go and Plus plans' Instant models, so choose a Thinking model in the model picker or use the Pro plan.
3. 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.
#### Example prompts
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](https://aws.github.io/aws-advanced-wrapper-docs/ruby/overview).
### Troubleshooting the Wrapper with AI Tools
A second skill, the troubleshooting assistant, helps an AI assistant find out why the wrapper isn't doing what you expect: installation and load errors, connection setup errors, IAM, Secrets Manager, AD FS and Okta authentication failures, failover that doesn't happen or fails, Active Record integration problems, the trilogy driver, Blue/Green, custom endpoints, Global Database, KMS encryption, telemetry, and performance. It works out whether the cause is your configuration, your environment (network, AWS permissions, TLS), a wrapper bug, or something outside the wrapper, helps you narrow it down and read the wrapper's logs, and drafts an issue report when the problem needs one.
The skill is [`skills/ruby-wrapper-troubleshooting-assistant/SKILL.md`](https://github.com/aws/aws-advanced-ruby-driver-wrapper/blob/v1.1.0/skills/ruby-wrapper-troubleshooting-assistant/SKILL.md) (link to the latest release), about 30,000 tokens on Claude Opus 5.5 and Sonnet 5.5 (about 20,000 in ChatGPT). The two skills are independent: install either one or both. Add it to your AI tool the same way as the configuration assistant (see [Quick start](#quick-start)), using the folder name `ruby-wrapper-troubleshooting-assistant`. For example, for Claude Code:
```bash
mkdir -p .claude/skills/ruby-wrapper-troubleshooting-assistant
curl -fsSL -o .claude/skills/ruby-wrapper-troubleshooting-assistant/SKILL.md \
https://raw.githubusercontent.com/aws/aws-advanced-ruby-driver-wrapper/v1.1.0/skills/ruby-wrapper-troubleshooting-assistant/SKILL.md
```
Then describe the problem, and include the error message and backtrace if you have one. Remove passwords and other secrets from anything you paste.
```
My Rails app on Aurora PostgreSQL gets AwsAdvancedRubyDriverWrapper::Errors::FailoverSuccessError
a few times a day, but there's no failover in the RDS events. What's going on?
```
```
Failover fails with "The request to discover the new topology timed out or was unsuccessful".
Here are the wrapper's debug logs:
<paste the logs>
```
The skill targets wrapper version 1.0.1 and later.
## Documentation
Technical documentation regarding the functionality of the AWS Advanced Ruby Driver Wrapper is published at the [AWS Advanced Wrapper documentation site](https://aws.github.io/aws-advanced-wrapper-docs/ruby/overview). Since the wrapper requires an underlying Ruby driver, please refer to the individual driver's documentation for driver-specific information.
| Topic | Documentation |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| Overview | [Overview](https://aws.github.io/aws-advanced-wrapper-docs/ruby/overview) |
| Failover Plugin | [Enhanced Failover Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/enhanced-failover) |
| Global Database Failover Plugin | [Global Database Failover Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/gdb-failover) |
| AWS IAM Authentication Plugin | [IAM Authentication Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/iam-authentication) |
| AWS Secrets Manager Plugin | [AWS Secrets Manager Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/aws-secrets-manager) |
| Custom Endpoint Plugin | [Custom Endpoint Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/custom-endpoint) |
| Blue/Green Deployment Plugin | [Blue/Green Deployment Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/blue-green) |
| Initial Connection Strategy Plugin | [Initial Connection Strategy Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/initial-connection-strategy) |
| KMS Encryption Plugin | [KMS Encryption Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/kms-encryption) |
| Configuring AWS Credentials | [AWS Credentials](https://aws.github.io/aws-advanced-wrapper-docs/ruby/aws-credentials) |
| Configuring TLS/SSL | [Configuring TLS/SSL](https://aws.github.io/aws-advanced-wrapper-docs/ruby/configuring-tls) |
| Plugin Compatibility | [Plugin Compatibility](https://aws.github.io/aws-advanced-wrapper-docs/ruby/compatibility) |
| Running the integration tests | [Integration Tests](https://aws.github.io/aws-advanced-wrapper-docs/ruby/development-guide/integration-tests) |
### Known Limitations
#### Trilogy MySQL Driver
- The KMS Encryption Plugin is not supported with `trilogy`, which has no prepared statements, so a bind parameter could only reach the server in plaintext. The plugin refuses to start on a `trilogy` connection.
- To authenticate with an IAM token, set `enable_cleartext_plugin: true` (and `ssl_mode`), since `trilogy` only sends the token with `mysql_clear_password` when that option is set.
#### Amazon RDS Blue/Green Deployments
Support for Blue/Green deployments using the wrapper requires specific metadata tables. Please refer to the plugin documentation for the supported database engine versions.
## Getting Help and Opening Issues
If you encounter a bug with the AWS Advanced Ruby Driver Wrapper, we would like to hear about it.
Please search the [existing issues](https://github.com/aws/aws-advanced-ruby-driver-wrapper/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. The [troubleshooting assistant skill](#troubleshooting-the-wrapper-with-ai-tools) can help you find the cause first, and draft the issue if it turns out to be a bug.
For all other questions, please use [GitHub discussions](https://github.com/aws/aws-advanced-ruby-driver-wrapper/discussions).
## How to Contribute
1. Set up your environment by following the directions in the [Contributing Guide](./CONTRIBUTING.md).
2. To contribute, first make a fork of this project.
3. Make any changes on your fork. Make sure you are aware of the requirements for the project.
4. Create a pull request from your fork.
5. Pull requests need to be approved and merged by maintainers into the main branch. <br />
**Note:** Before making a pull request, run all tests and verify everything is passing.
## Other AWS Advanced Wrapper Drivers
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 |
## License
This software is released under the Apache 2.0 license.