aws_advanced_ruby_driver_wrapper 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab8433b9c38b4c70ea438830ccc3d870bdd56141e5be9ad28e309aad7852074
-  data.tar.gz: bfc31bb5bbd87b1a3bb2ee416cc0208b79bd15c9e92422266822cc5a0904b0f5
+  metadata.gz: b3f6f4cf5575f7126636ad09c23b81a3feec7544b36c7fd3a1d13cb159f0978d
+  data.tar.gz: e5053d0035262786e689706ecc48788fd031c06b4144f2cc3e15e0dba2d44589
 SHA512:
-  metadata.gz: f321a9d2942e5cef6eada081baa62f5cedc42b906b8f991ab42bb9ee55bd6323381b0aa781090427e1f4d9b5a1c6ac9d2e32aadf0e2d4dfd476dc57ef34217d1
-  data.tar.gz: d6125a87b85478e47d4f851ff7c9d7a0a6aa6a14806575e6b77df86bff38f458c516497bc3c458abd0ccc66937fb1de1f77164d64c324bed60ee1786f7e7035d
+  metadata.gz: 8c3bfe267a552d4542b4b89944c76f35442ffbe1a16fde107126660b8aa0e352f932353fba29e67029db860fda83aea0c3acace10c3997a4a50b7b0bc89d0652
+  data.tar.gz: fe7c1b9e226219d8740daa00f0f101004e3c869044cac2b7b950a8cf6447c6ebc9ac418c2fcc30ea3c86767d72cb9091ce18c587d19fbae4663d174fd20f98b5

data/CHANGELOG.md

@@ -3,7 +3,51 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/#semantic-versioning-200).
 
-## [1.0.0] - 2026-10-02
+## [1.1.0] - 2026-11-05
+
+### :magic_wand: Added
+- [Federated Authentication Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/federated-auth), which authenticates with Active Directory Federation Services (AD FS), exchanges the resulting SAML assertion for temporary AWS credentials via STS, and connects to the database with an RDS IAM authentication token. Enabled with the `federated_auth` plugin code ([PR #207](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/207)).
+- [Okta Authentication Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/okta-auth), which uses the same SAML-to-STS flow as AD FS but against Okta, is also available via the `okta` plugin code ([PR #215](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/215)).
+- [Telemetry](https://aws.github.io/aws-advanced-wrapper-docs/ruby/telemetry) through OpenTelemetry. With `enable_telemetry` set, the wrapper records traces of each wrapper call, the plugins it passes through, and the driver, plus failover, Blue/Green switchover, and authentication spans, and metrics such as failover and token fetch counts. Traces and metrics are sent wherever the application's OpenTelemetry SDK exports them. The OpenTelemetry gems are optional dependencies ([PR #220](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/220), [PR #225](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/225)).
+- Support for the [`trilogy`](https://rubygems.org/gems/trilogy) MySQL driver, through the `WrapperTrilogyClient` connection class and the drop-in `aws_trilogy` ActiveRecord adapter. The KMS Encryption Plugin is not supported with `trilogy` ([PR #203](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/203)).
+- The [Blue/Green Deployment plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/blue-green) now invalidates connections that were opened to the old blue environment before a switchover, controlled by the new `bg_drop_blue_connections` property (default `true`). Once a switchover is confirmed, each such connection is closed the next time it is used, so with the failover plugin enabled it fails over through Blue/Green routing and raises `FailoverSuccessError` (or `TransactionStateUnknownError` inside a transaction), and without failover the driver raises its closed-connection error ([PR #223](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/223)).
+- AI assistant skills for the wrapper, in the repository under [`skills/`](https://github.com/aws/aws-advanced-ruby-driver-wrapper/tree/main/skills): a [configuration assistant](https://github.com/aws/aws-advanced-ruby-driver-wrapper/tree/main/skills/ruby-wrapper-configuration-assistant) that builds a working configuration through an interview, reviews existing configurations, and answers parameter and plugin questions, and a [troubleshooting assistant](https://github.com/aws/aws-advanced-ruby-driver-wrapper/tree/main/skills/ruby-wrapper-troubleshooting-assistant) that diagnoses errors and unexpected behavior and classifies the cause as configuration, environment, wrapper bug, or not the wrapper. Both are self-contained and grounded in the wrapper source and the official Ruby docs ([PR #214](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/214), [PR #219](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/219), [PR #233](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/233), [PR #237](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/237), [PR #239](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/239)).
+
+### :crab: Changed
+- Simplified the KMS Encryption Plugin's PostgreSQL trigger SQL to read the column's HMAC key from `key_storage` for every row. Re-run the trigger SQL from the [documentation](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/kms-encryption#postgresql-1) to update existing deployments ([PR #216](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/216)).
+- The KMS Encryption Plugin's trigger SQL now ships with the gem and is stamped with its version, so deployed triggers can be checked against the version in use ([PR #218](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/218)).
+- With `mysql2` (`WrapperMysql2Client` and the `aws_mysql2` ActiveRecord adapter), the failover plugin now fails over on a `read_timeout`, when MySQL 8.0.24+ disconnects a connection that exceeded `wait_timeout` (error 4031), and on a lost connection reported as error 2055 (`CR_SERVER_LOST_EXTENDED`), matching `trilogy`. Before, none of these triggered failover: a `read_timeout` raised `Mysql2::Error::TimeoutError` (`ActiveRecord::AdapterTimeout` under `aws_mysql2`), and errors 4031 and 2055 were raised as-is (`ActiveRecord::ConnectionFailed` under `aws_mysql2`, which ActiveRecord answered by reconnecting to the original endpoint and retrying queries it considers retryable). **Behavior change:** these errors now fail over and raise `FailoverSuccessError` (or `TransactionStateUnknownError` inside a transaction), which ActiveRecord does not retry. This includes:
+  - a query that runs longer than `read_timeout`. Set `read_timeout` higher than your slowest expected query.
+  - the first query on a pooled connection that sat idle longer than the server's `wait_timeout`. Raise `wait_timeout`, or have the pool reap idle connections sooner (for example with ActiveRecord's `idle_timeout`).
+
+  Lock wait timeouts (error 1205) still do not trigger failover ([PR #234](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/234)).
+- Declared `bigdecimal` and `logger` as runtime dependencies, since Ruby no longer installs them by default from 3.4 (`bigdecimal`) and 4.0 (`logger`) on, and dropped the need for `base64` and the full `cgi` library. This keeps a bundle that does not otherwise include them, such as an app using the drivers without ActiveRecord, from failing to load the wrapper ([PR #224](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/224)).
+
+### :bug: Fixed
+- Fixed the Custom Endpoint Plugin signing its RDS API calls with the default credential chain instead of the configured `aws_credentials_provider`, so a custom endpoint could not be resolved in an account reachable only through the configured credentials ([PR #205](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/205)).
+- Fixed an unknown host selection strategy being accepted at configuration time and only failing later during connection use. An invalid strategy is now rejected when the connection is set up ([PR #206](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/206)).
+- Fixed `iam_access_token_property_name`, `cluster_id`, and `bgd_id` not accepting YAML-typed (non-string) values from `database.yml`, such as a numeric `cluster_id` ([PR #209](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/209)).
+- Fixed the block form of `pg`'s `exec`, `query`, `exec_params`, and `exec_prepared` not working through `WrapperPgConnection`. The wrapper now yields the result to the block, clears it when the block returns, and returns the block's value, matching `pg` ([PR #221](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/221)).
+- Fixed the cluster topology and custom endpoint monitors stopping when their stored data was read, which could leave the wrapper with a stale topology so failover could not find the new writer ([PR #226](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/226)).
+- Fixed the KMS Encryption Plugin matching MySQL placeholders to the wrong encrypted columns when the statement contained comments, so values could be encrypted against the wrong column ([PR #227](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/227)).
+- Fixed several ActiveRecord error-handling gaps: a `nil` connection is now recognized as a connection error; a `pg` IAM authentication failure is classified as a connection error rather than `ActiveRecord::NoDatabaseError`; `trilogy` schema errors are identified correctly; and `ping` and `close` now match the underlying driver's behavior ([PR #228](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/228)).
+
+## [1.0.1] - 2026-10-07
+
+### :bug: Fixed
+- Fixed the `aws_postgresql` ActiveRecord adapter passing ActiveRecord-only `database.yml` keys, such as the Rails 8.1 pool settings (`max_connections`, `min_connections`, `keepalive`, `max_age`) and multi-database settings (`replica`, `migrations_paths`, `database_tasks`), to `pg`, which rejected them with `PG::Error: invalid connection option` ([PR #191](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/191)).
+- Fixed the `aws_mysql2` ActiveRecord adapter dropping the `flags`, `encoding`, `socket`, and `reconnect` client options, which removed ActiveRecord's `FOUND_ROWS` flag so that statements such as `update_all` reported changed rows instead of matched rows ([PR #193](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/193)).
+- Fixed the `aws_postgresql` and `aws_mysql2` ActiveRecord adapters not translating connection errors the way the standard adapters do, so a missing database was not reported as `ActiveRecord::NoDatabaseError` and `db:prepare` (and `bin/setup`) failed instead of creating it ([PR #193](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/193)).
+- Fixed the `aws_postgresql` and `aws_mysql2` ActiveRecord adapters keeping ActiveRecord's prepared statement cache after a successful failover, so every query prepared before the failover failed on that connection with `Method invoked against old connection` until the process restarted ([PR #194](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/194), [documentation](https://aws.github.io/aws-advanced-wrapper-docs/ruby/enhanced-failover)).
+- Fixed `db:drop`, `db:reset`, and `db:test:prepare` failing on Aurora PostgreSQL with `database "<name>" is being accessed by other users`. The same error occurred when running `bin/rails test` after a schema change. The cause was the wrapper's topology and Blue/Green monitors, which kept their own connections open to the database being dropped. The wrapper now stops these monitors before dropping a database and when ActiveRecord clears all its connections ([PR #195](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/195)).
+- Fixed forked processes, such as Puma workers with `preload_app!`, Unicorn workers, and Resque jobs, inheriting the parent's background monitors after their threads had stopped, so the cluster topology never refreshed in the child and failover there could not find the new writer. A forked child now starts its own monitors and leaves the parent's monitoring connections open. A forked child also no longer waits on a Secrets Manager fetch that was in progress in the parent when it forked ([PR #196](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/196)).
+- Fixed the AWS Secrets Manager plugin not reporting a timed-out secret fetch as a timeout. A fetch that did not finish within 60 seconds failed with a generic `SecretsManagerAuthError` (`Failed to fetch database credentials from AWS Secrets Manager`) instead of `Timed out fetching secret after 60s` ([PR #196](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/196)).
+- Fixed Action Cable's PostgreSQL subscription adapter (`adapter: postgresql` in `cable.yml`) refusing to run on the `aws_postgresql` ActiveRecord adapter with `The Active Record database must be PostgreSQL in order to use the PostgreSQL Action Cable storage adapter`, which also stopped Turbo Stream broadcasts ([PR #197](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/197)).
+- Fixed the `aws_postgresql` and `aws_mysql2` ActiveRecord adapters raising `Unknown type` for adapter-specific attribute types and columns. ActiveRecord keys its type registry by the connection's adapter name, and the wrapped adapters registered none of their own, so types such as PostgreSQL `:interval`, `:point`, `:uuid`, array, and range, and MySQL `:unsigned_integer`, could not be resolved. The wrapped adapter names are now aliased to the underlying `postgresql` and `mysql2` adapters for type registration and lookup, so the wrapped adapters resolve the same types as the standard adapters ([PR #200](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/200)).
+  - **Side effect:** in an application that uses both a standard (`postgresql`/`mysql2`) connection and a wrapped (`aws_postgresql`/`aws_mysql2`) connection, a type registered for one is now shared with the other, because both resolve under the same underlying adapter key.
+- Changed the `aws_postgresql` and `aws_mysql2` ActiveRecord adapters to report the underlying `adapter_name` (`"PostgreSQL"` and `"Mysql2"`) instead of `"AwsPostgreSQL"` and `"AwsMySQL2"`. ActiveRecord's migration compatibility layer gates PostgreSQL- and MySQL-specific behavior on `connection.adapter_name` string comparisons. Legacy versioned migrations (`ActiveRecord::Migration[5.0]` through `[7.0]`) now complete as expected ([PR #200](https://github.com/aws/aws-advanced-ruby-driver-wrapper/pull/200)).
+
+## [1.0.0] - 2026-10-05
 
 The Amazon Web Services (AWS) Advanced Ruby Driver Wrapper allows an application to take advantage of the features of clustered Aurora databases.
 
@@ -20,4 +64,6 @@ The Amazon Web Services (AWS) Advanced Ruby Driver Wrapper allows an application
 - [Initial Connection Strategy Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/initial-connection-strategy).
 - [KMS Encryption Plugin](https://aws.github.io/aws-advanced-wrapper-docs/ruby/using-plugins/kms-encryption).
 
-[1.0.0]: https://github.com/aws/aws-advanced-ruby-driver-wrapper/releases/tag/1.0.0
+[1.1.0]: https://github.com/aws/aws-advanced-ruby-driver-wrapper/releases/tag/v1.1.0
+[1.0.1]: https://github.com/aws/aws-advanced-ruby-driver-wrapper/releases/tag/v1.0.1
+[1.0.0]: https://github.com/aws/aws-advanced-ruby-driver-wrapper/releases/tag/v1.0.0

data/README.md

@@ -4,7 +4,7 @@
 
 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` and `aws_postgresql` adapters that sit on top of the community [`mysql2`](https://rubygems.org/gems/mysql2) and [`pg`](https://rubygems.org/gems/pg) drivers.
+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
 
@@ -54,10 +54,12 @@ Add this line to your application's Gemfile:
 gem 'aws_advanced_ruby_driver_wrapper'
 ```
 
-For MySQL users, also install the underlying driver:
+For MySQL users, also install one of the underlying drivers:
 
 ```ruby
 gem 'mysql2'
+# or
+gem 'trilogy'
 ```
 
 For PostgreSQL users, also install the underlying driver:
@@ -74,14 +76,17 @@ bundle install
 
 ## Getting Started
 
-The wrapper registers two ActiveRecord adapters — `aws_mysql2` and `aws_postgresql` — that are drop-in replacements for the standard `mysql2` and `postgresql` adapters.
+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
+# 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'
 ```
@@ -89,7 +94,7 @@ 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
+# MySQL (use aws_trilogy with the trilogy driver)
 production:
   adapter: aws_mysql2
   host: my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com
@@ -106,6 +111,105 @@ production:
   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.
@@ -128,6 +232,11 @@ Technical documentation regarding the functionality of the AWS Advanced Ruby Dri
 
 ### 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.
@@ -137,7 +246,7 @@ Support for Blue/Green deployments using the wrapper requires specific metadata
 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.
+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).
 

data/THIRD-PARTY-LICENSES

@@ -3,10 +3,10 @@ following third-party software. The applicable licenses and notices are
 reproduced below. Each dependency remains under its own license; nothing in
 this file modifies those terms.
 
-The underlying database drivers (pg, mysql2), ActiveRecord, pg_query, and the
-AWS SDK gems are optional dependencies that are installed by the user as needed;
-they are listed here because the wrapper is designed to load and run on top of
-them.
+The underlying database drivers (pg, mysql2, trilogy), ActiveRecord, pg_query,
+the OpenTelemetry gems, and the AWS SDK gems are optional dependencies that are
+installed by the user as needed; they are listed here because the wrapper is
+designed to load and run on top of them.
 
 ===============================================================================
 
@@ -40,6 +40,19 @@ SOFTWARE.
 
 -----------
 
+The following Ruby gems are required runtime dependencies of this product.
+Ruby no longer installs them by default from Ruby 3.4 (bigdecimal) and 4.0
+(logger) on, so the wrapper declares them explicitly:
+
+ - bigdecimal@4.1.3
+ - logger@1.7.0
+
+These packages are each distributed under the same Ruby license reproduced
+below for the `pg` gem (the Ruby license or, at your option, the 2-clause
+BSDL).
+
+-----------
+
 The following Ruby gem may be used with this product (ActiveRecord adapters):
 
  - activerecord@8.1.4
@@ -131,9 +144,41 @@ SOFTWARE.
 
 -----------
 
+The following Ruby gem may be used with this product (alternative MySQL driver;
+the KMS Encryption plugin is not supported with trilogy):
+
+ - trilogy@2.13.2
+
+This package contains the following license and notice below:
+
+Copyright (c) 2012-2021 GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+-----------
+
 The following Ruby gem may be used with this product (PostgreSQL driver):
 
- - pg@1.6.3
+ - pg@1.7.0
 
 This package contains the following license and notice below:
 
@@ -224,7 +269,7 @@ SUCH DAMAGE.
 The following Ruby gem may be used with this product (SQL statement parsing
 for the KMS Encryption plugin):
 
- - pg_query@6.2.3
+ - pg_query@6.2.5
 
 This package contains the following license and notice below:
 
@@ -259,13 +304,27 @@ POSSIBILITY OF SUCH DAMAGE.
 
 -----------
 
+The following OpenTelemetry for Ruby gems may be used with this product
+(telemetry, when `enable_telemetry` is set). The wrapper loads these API gems;
+the OpenTelemetry SDK and exporters that actually emit the traces and metrics
+are supplied by the application:
+
+ - opentelemetry-api@1.11.1
+ - opentelemetry-metrics-api@0.10.0
+
+These packages are each licensed under the Apache License, Version 2.0,
+reproduced below (following the AWS SDK gems).
+
+-----------
+
 The following AWS SDK for Ruby gems may be used with this product (AWS IAM
-Authentication, AWS Secrets Manager, Custom Endpoint, and KMS Encryption
-plugins):
+Authentication, AWS Secrets Manager, Custom Endpoint, Federated Authentication,
+Okta Authentication, and KMS Encryption plugins):
 
- - aws-sdk-kms@1.132.0
- - aws-sdk-rds@1.323.0
- - aws-sdk-secretsmanager@1.136.0
+ - aws-sdk-core@3.263.0
+ - aws-sdk-kms@1.138.0
+ - aws-sdk-rds@1.329.0
+ - aws-sdk-secretsmanager@1.141.0
 
 These packages are each licensed under the Apache License, Version 2.0,
 reproduced below:

data/aws_advanced_ruby_driver_wrapper.gemspec

@@ -53,7 +53,12 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  # The wrapper requires bigdecimal and logger, and Ruby no longer installs them by default from 3.4
+  # (bigdecimal) and 4.0 (logger) on. Declaring them keeps a bundle that does not otherwise include
+  # them, such as an app using the drivers without Active Record, from failing to load the wrapper.
+  spec.add_dependency 'bigdecimal'
   spec.add_dependency 'concurrent-ruby', '~> 1.3', '>= 1.3.7'
+  spec.add_dependency 'logger'
 
   spec.post_install_message = <<~MSG
     ═══════════════════════════════════════════════════════════════
@@ -63,6 +68,10 @@ Gem::Specification.new do |spec|
       gem install mysql2
       require 'aws_advanced_ruby_driver_wrapper/mysql'
 
+    To use with MySQL through trilogy:
+      gem install trilogy
+      require 'aws_advanced_ruby_driver_wrapper/trilogy'
+
     To use with PostgreSQL:
       gem install pg
       require 'aws_advanced_ruby_driver_wrapper/postgresql'

data/lib/aws_advanced_ruby_driver_wrapper/active_record/aws_action_cable_postgresql_support.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative '../postgresql'
+
+module ActiveRecord
+  module ConnectionAdapters
+    # Lets Action Cable's PostgreSQL subscription adapter (cable.yml `adapter: postgresql`) run on the
+    # aws_postgresql adapter. Action Cable refuses any raw connection that is not a PG::Connection, and
+    # aws_postgresql hands out a WrapperPgConnection, which forwards the calls Action Cable makes
+    # (exec, escape_identifier, escape_string, wait_for_notify) to the PG::Connection it wraps.
+    module AwsActionCablePostgreSQLSupport
+      private
+
+      def verify!(pg_conn)
+        super unless pg_conn.is_a?(AwsAdvancedRubyDriverWrapper::WrapperPgConnection)
+      end
+    end
+  end
+end
+
+# Action Cable runs this hook when its server loads, before it loads a subscription adapter, so the
+# PostgreSQL one is loaded here to patch it. Applications without Action Cable never run the hook.
+ActiveSupport.on_load(:action_cable) do
+  require 'action_cable/subscription_adapter/postgresql'
+  ActionCable::SubscriptionAdapter::PostgreSQL.prepend(ActiveRecord::ConnectionAdapters::AwsActionCablePostgreSQLSupport)
+end

data/lib/aws_advanced_ruby_driver_wrapper/active_record/aws_connection_handler.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require 'active_record'
+require_relative '../services/service_utility'
+require_relative '../host/rds_host_list_provider'
+require_relative '../plugins/blue_green/blue_green_plugin'
+
+module ActiveRecord
+  module ConnectionAdapters
+    # Stops the wrapper's background monitors and Blue/Green status providers when ActiveRecord closes every
+    # connection pool, and forgets the state they cached, so that the next connection starts new ones straight away.
+    #
+    # The monitors keep their own connections to the database, outside ActiveRecord's pools. Closing
+    # everything is what ActiveRecord does before another process takes over the database, for example
+    # when bin/rails test runs db:test:prepare in a child process to drop and reload the test database,
+    # and PostgreSQL refuses to drop a database that a monitor is still connected to. The next
+    # connection that needs a monitor starts a new one.
+    module AwsConnectionHandler
+      def clear_all_connections!(...)
+        super
+        core = AwsAdvancedRubyDriverWrapper::Services::CoreServices
+        core.monitor_service.stop_and_remove_all
+        AwsAdvancedRubyDriverWrapper::Plugins::BlueGreen::BlueGreenPlugin.clean_up_providers
+        # Without this, connections would keep reading cached state that nothing refreshes any more.
+        cached = [AwsAdvancedRubyDriverWrapper::Host::RdsHostListProvider::TOPOLOGY_CACHE_NAME,
+                  AwsAdvancedRubyDriverWrapper::Plugins::BlueGreen::BlueGreenPlugin::BLUE_GREEN_NAME]
+        cached.each { |name| core.storage_service.clear(name) if core.storage_service.registered?(name) }
+      end
+    end
+
+    ConnectionHandler.prepend(AwsConnectionHandler)
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/active_record/aws_mysql2_adapter.rb

@@ -17,20 +17,31 @@
 require 'active_record/connection_adapters/mysql2_adapter'
 require_relative '../mysql'
 require_relative '../errors'
-require_relative '../utils/ar_constants'
+require_relative 'type_adapter_alias'
+require_relative 'aws_connection_handler'
 
 module ActiveRecord
   module ConnectionAdapters
     class AwsMysql2Adapter < Mysql2Adapter
-      ADAPTER_NAME = 'AwsMySQL2'
-
-      # ActiveRecord-only keys that should not be passed to the wrapper or native driver.
-      AR_ONLY_KEYS = AwsAdvancedRubyDriverWrapper::Utils::AR_COMMON_KEYS
-
-      def adapter_name = ADAPTER_NAME
-
+      # Passes the whole config on, as the parent adapter does: the wrapper takes its own properties out,
+      # and mysql2 reads the client options it knows (including the FOUND_ROWS flag the parent adds) and
+      # ignores the ActiveRecord-only keys.
+      #
+      # Translates connection errors the same way the parent adapter does, so ActiveRecord can tell a
+      # missing database (which db:prepare creates) or rejected credentials from other failures.
       def self.new_client(config)
-        AwsAdvancedRubyDriverWrapper::WrapperMysql2Client.new(**config.except(*AR_ONLY_KEYS))
+        AwsAdvancedRubyDriverWrapper::WrapperMysql2Client.new(**config)
+      rescue ::Mysql2::Error => e
+        case e.error_number
+        when ER_BAD_DB_ERROR
+          raise ActiveRecord::NoDatabaseError.db_error(config[:database])
+        when ER_DBACCESS_DENIED_ERROR, ER_ACCESS_DENIED_ERROR
+          raise ActiveRecord::DatabaseConnectionError.username_error(config[:username])
+        when ER_CONN_HOST_ERROR, ER_UNKNOWN_HOST_ERROR
+          raise ActiveRecord::DatabaseConnectionError.hostname_error(config[:host])
+        else
+          raise ActiveRecord::ConnectionNotEstablished, e.message
+        end
       end
 
       def connect
@@ -53,6 +64,9 @@ module ActiveRecord
         return super unless exception.is_a?(AwsAdvancedRubyDriverWrapper::Errors::AwsError)
 
         if exception.needs_reconfiguration
+          # The wrapper has reconnected this connection object to a new physical connection, where the
+          # statements prepared on the old one do not exist. Forget them so they are prepared again.
+          clear_cache!(new_connection: true)
           configure_connection
           exception
         elsif exception.is_a?(AwsAdvancedRubyDriverWrapper::Errors::FailoverFailedError)