aws_advanced_ruby_driver_wrapper 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6da8d07797b41d2bef7c26ac10bff8a3fcf6050d098344d3e850cf80d88305a9
-  data.tar.gz: 2f17adb4cca840143bacbf16056d67748f12204f22a5beb71ddb8bdc445aca3e
+  metadata.gz: b3f6f4cf5575f7126636ad09c23b81a3feec7544b36c7fd3a1d13cb159f0978d
+  data.tar.gz: e5053d0035262786e689706ecc48788fd031c06b4144f2cc3e15e0dba2d44589
 SHA512:
-  metadata.gz: dc3f77408c42d2a2dde71cce86af1c0bb294380b6e7c679c51118e0fd2383f4d677e95d77521cbe974bf3c584e5f7af7b65244834a0489034d7ab9541982dcc6
-  data.tar.gz: fcfaa69564b9abfeed8095e5995a9893a636def8ea0f8c1ad471bbcf69a0f36f7593090b42f76083556c7ee834350238bc73c8e090408572ccf78b8a01ee858f
+  metadata.gz: 8c3bfe267a552d4542b4b89944c76f35442ffbe1a16fde107126660b8aa0e352f932353fba29e67029db860fda83aea0c3acace10c3997a4a50b7b0bc89d0652
+  data.tar.gz: fe7c1b9e226219d8740daa00f0f101004e3c869044cac2b7b950a8cf6447c6ebc9ac418c2fcc30ea3c86767d72cb9091ce18c587d19fbae4663d174fd20f98b5

data/CHANGELOG.md

@@ -3,6 +3,35 @@ 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.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
@@ -35,5 +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.1]: https://github.com/aws/aws-advanced-ruby-driver-wrapper/releases/tag/1.0.1
-[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_postgresql_adapter.rb

@@ -63,23 +63,37 @@ module ActiveRecord
         superclass.native_database_types.merge(datetime: NATIVE_DATABASE_TYPES[datetime_type])
       end
 
+      # SQLSTATEs and FATAL-message signals for an authentication/authorization rejection (invalid
+      # password, PAM failure, pg_hba.conf rejection). A failed *connect* usually carries no result, so
+      # the message text is the reliable signal and the SQLSTATE is only a bonus when one is present.
+      AUTH_REJECTION_SQLSTATES = %w[28P01 28000].freeze
+      AUTH_REJECTION_MESSAGE = /password authentication failed|PAM authentication failed|pg_hba\.conf/
+
       # Note that this config includes wrapper properties.
       #
-      # 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.
+      # Mirrors the parent PostgreSQLAdapter.new_client so ActiveRecord can tell a missing database
+      # (which db:prepare creates) or rejected credentials from other failures.
       def self.new_client(config)
         AwsAdvancedRubyDriverWrapper::WrapperPgConnection.new(**config)
       rescue ::PG::Error => e
         dbname, user, host = config.values_at(:dbname, :user, :host)
         # The postgres maintenance database always exists, so a failure there is not a missing database.
         raise ActiveRecord::ConnectionNotEstablished, e.message if dbname == 'postgres'
-        raise ActiveRecord::NoDatabaseError.db_error(dbname) if dbname && e.message.include?(dbname)
+        raise ActiveRecord::NoDatabaseError.db_error(dbname) if dbname && e.message.include?(dbname) && !auth_rejection?(e)
         raise ActiveRecord::DatabaseConnectionError.username_error(user) if user && e.message.include?(user)
         raise ActiveRecord::DatabaseConnectionError.hostname_error(host) if host && e.message.include?(host)
 
         raise ActiveRecord::ConnectionNotEstablished, e.message
       end
 
+      # @return [Boolean] whether the PG error is an authentication/authorization rejection, by SQLSTATE
+      #   when the error carries a result and otherwise by its canonical FATAL text.
+      def self.auth_rejection?(error)
+        sqlstate = error.result&.error_field(PG::PG_DIAG_SQLSTATE)
+        AUTH_REJECTION_SQLSTATES.include?(sqlstate) || error.message.match?(AUTH_REJECTION_MESSAGE)
+      end
+      private_class_method :auth_rejection?
+
       def connect
         @connection_broken = false
         # Override @connection_parameters with the full config so the parent's

data/lib/aws_advanced_ruby_driver_wrapper/active_record/aws_trilogy_adapter.rb

@@ -0,0 +1,80 @@
+# 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/connection_adapters/trilogy_adapter'
+require_relative '../trilogy'
+require_relative '../errors'
+require_relative 'type_adapter_alias'
+require_relative 'aws_connection_handler'
+
+module ActiveRecord
+  module ConnectionAdapters
+    class AwsTrilogyAdapter < TrilogyAdapter
+      # Connects as the parent adapter does, through the wrapper instead of trilogy itself: the ssl_mode
+      # name is turned into the constant trilogy reads, and the whole config is passed on, since the
+      # wrapper takes its own properties out and trilogy 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)
+        config[:ssl_mode] = parse_ssl_mode(config[:ssl_mode]) if config[:ssl_mode]
+        AwsAdvancedRubyDriverWrapper::WrapperTrilogyClient.new(config)
+      rescue ::Trilogy::Error => e
+        raise translate_connect_error(config, e)
+      end
+
+      def connect
+        @connection_broken = false
+        super
+      end
+
+      def reconnect
+        @connection_broken = false
+        super
+      end
+
+      def active?
+        return false if @connection_broken
+
+        super
+      end
+
+      def translate_exception(exception, message:, sql:, binds:)
+        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
+          # session ActiveRecord configured on the old one does not exist. Forget what was cached about
+          # that connection and configure the new one.
+          clear_cache!(new_connection: true)
+          configure_connection
+          exception
+        elsif exception.is_a?(AwsAdvancedRubyDriverWrapper::Errors::FailoverFailedError)
+          @connection_broken = true
+          ActiveRecord::ConnectionFailed.new(message, sql:, binds:, connection_pool: @pool)
+        else
+          exception
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters.register(
+  'aws_trilogy',
+  'ActiveRecord::ConnectionAdapters::AwsTrilogyAdapter',
+  'aws_advanced_ruby_driver_wrapper/active_record/aws_trilogy_adapter'
+)

data/lib/aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias.rb

@@ -37,7 +37,7 @@ module AwsAdvancedRubyDriverWrapper
   # type explicitly registered for :aws_postgresql is normalized to :postgresql and so also applies
   # to the plain postgresql connections (and vice versa). This is documented in the CHANGELOG.
   module TypeAdapterAlias
-    ADAPTER_ALIASES = { aws_postgresql: :postgresql, aws_mysql2: :mysql2 }.freeze
+    ADAPTER_ALIASES = { aws_postgresql: :postgresql, aws_mysql2: :mysql2, aws_trilogy: :trilogy }.freeze
 
     # Prepended onto ActiveRecord::Type::AdapterSpecificRegistry. Normalizing the adapter in lookup
     # covers both the framework path and a direct Type.lookup(..., adapter: :aws_postgresql); any

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/driver_dialect.rb

@@ -33,6 +33,17 @@ module AwsAdvancedRubyDriverWrapper
 
       DEFAULT_MONITORING_TIMEOUT_SEC = 5
 
+      # @return [String] the name of the Ruby driver gem this dialect drives
+      def name
+        raise NotImplementedError
+      end
+
+      # The database engine the driver talks to, which decides the database dialects that apply.
+      # @return [Symbol] +:mysql+ or +:postgresql+
+      def database_engine
+        raise NotImplementedError
+      end
+
       def connect(host_info, config)
         raise NotImplementedError
       end
@@ -138,6 +149,29 @@ module AwsAdvancedRubyDriverWrapper
         :user
       end
 
+      # Returns the property key the underlying driver expects for the TLS CA certificate file.
+      # Used by Blue/Green substitute routing for drivers that overload the host for both the socket
+      # address and the TLS server name (mysql2, trilogy): it tells whether TLS is active before
+      # deciding to connect by hostname rather than raw IP, avoiding a certificate-name mismatch.
+      # Drivers that can pin the socket separately (see #props_pinned_to_ip) do not use this.
+      # mysql2 names it +:sslca+ (the default); override where it differs (trilogy uses +:ssl_ca+).
+      def tls_ca_property_key
+        :sslca
+      end
+
+      # Blue/Green substitute routing must connect to a specific instance IP — so a DNS lookup during
+      # the switchover window cannot resolve to the old instance — while still presenting the original
+      # hostname for TLS certificate verification and IAM token generation. A driver that can pin the
+      # socket address separately from the TLS/auth server name returns a copy of +driver_props+ that
+      # connects to +ip+ but keeps the hostname for verification; a driver that overloads the host for
+      # both returns +nil+, and the routing falls back to the #tls_ca_property_key hostname check.
+      # @param driver_props [Hash]
+      # @param ip [String] the instance IP to pin the socket to
+      # @return [Hash, nil] props pinned to +ip+, or +nil+ when the driver cannot split socket from TLS name
+      def props_pinned_to_ip(_driver_props, _ip)
+        nil
+      end
+
       # Applies default socket/connect timeouts to monitoring connection driver props.
       # These ensure that a query or close on a dead connection raises a timeout error
       # rather than hanging indefinitely or segfaulting.
@@ -154,6 +188,15 @@ module AwsAdvancedRubyDriverWrapper
       def reported_in_transaction(_connection)
         nil
       end
+
+      # The server version that decides which versioned /*!80023 ... */ executable comments the server
+      # runs, as MySQL numbers it (8.0.39 is 80039). Only MySQL has executable comments.
+      # @param connection [Object]
+      # @return [Integer, nil] nil when the driver's SQL has no executable comments, or the version
+      #   cannot be read
+      def executable_comment_version(_connection)
+        nil
+      end
     end
   end
 end

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/driver_dialect_manager.rb

@@ -14,26 +14,33 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-require_relative 'mysql_driver_dialect'
+require_relative 'mysql2_driver_dialect'
 require_relative 'pg_driver_dialect'
+require_relative 'trilogy_driver_dialect'
 require_relative '../errors'
 require_relative '../errors/mysql_error_handler'
 require_relative '../errors/pg_error_handler'
+require_relative '../errors/trilogy_error_handler'
 
 module AwsAdvancedRubyDriverWrapper
   module DriverDialects
     module DriverDialectManager
-      MYSQL_DIALECT = MysqlDriverDialect.new.freeze
+      MYSQL2_DIALECT = Mysql2DriverDialect.new.freeze
       PG_DIALECT = PgDriverDialect.new.freeze
+      TRILOGY_DIALECT = TrilogyDriverDialect.new.freeze
 
       REGISTRY = {
         mysql2: {
-          driver_dialect: MYSQL_DIALECT,
-          error_handler: Errors::MysqlErrorHandler.new(MYSQL_DIALECT)
+          driver_dialect: MYSQL2_DIALECT,
+          error_handler: Errors::MysqlErrorHandler.new(MYSQL2_DIALECT)
         },
         postgresql: {
           driver_dialect: PG_DIALECT,
           error_handler: Errors::PgErrorHandler.new(PG_DIALECT)
+        },
+        trilogy: {
+          driver_dialect: TRILOGY_DIALECT,
+          error_handler: Errors::TrilogyErrorHandler.new(TRILOGY_DIALECT)
         }
       }.freeze