Repository navigation
[1.1.0] - 2026-11-05
🪄 Added
- Federated Authentication Plugin, 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_authplugin code (PR #207). - Okta Authentication Plugin, which uses the same SAML-to-STS flow as AD FS but against Okta, is also available via the
oktaplugin code (PR #215). - Telemetry through OpenTelemetry. With
enable_telemetryset, 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, PR #225). - Support for the
trilogyMySQL driver, through theWrapperTrilogyClientconnection class and the drop-inaws_trilogyActiveRecord adapter. The KMS Encryption Plugin is not supported withtrilogy(PR #203). - The Blue/Green Deployment plugin now invalidates connections that were opened to the old blue environment before a switchover, controlled by the new
bg_drop_blue_connectionsproperty (defaulttrue). 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 raisesFailoverSuccessError(orTransactionStateUnknownErrorinside a transaction), and without failover the driver raises its closed-connection error (PR #223). - AI assistant skills for the wrapper, in the repository under
skills/: a configuration assistant that builds a working configuration through an interview, reviews existing configurations, and answers parameter and plugin questions, and a 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, PR #219, PR #233, PR #237, PR #239).
🦀 Changed
-
Simplified the KMS Encryption Plugin's PostgreSQL trigger SQL to read the column's HMAC key from
key_storagefor every row. Re-run the trigger SQL from the documentation to update existing deployments (PR #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).
-
With
mysql2(WrapperMysql2Clientand theaws_mysql2ActiveRecord adapter), the failover plugin now fails over on aread_timeout, when MySQL 8.0.24+ disconnects a connection that exceededwait_timeout(error 4031), and on a lost connection reported as error 2055 (CR_SERVER_LOST_EXTENDED), matchingtrilogy. Before, none of these triggered failover: aread_timeoutraisedMysql2::Error::TimeoutError(ActiveRecord::AdapterTimeoutunderaws_mysql2), and errors 4031 and 2055 were raised as-is (ActiveRecord::ConnectionFailedunderaws_mysql2, which ActiveRecord answered by reconnecting to the original endpoint and retrying queries it considers retryable). Behavior change: these errors now fail over and raiseFailoverSuccessError(orTransactionStateUnknownErrorinside a transaction), which ActiveRecord does not retry. This includes:- a query that runs longer than
read_timeout. Setread_timeouthigher than your slowest expected query. - the first query on a pooled connection that sat idle longer than the server's
wait_timeout. Raisewait_timeout, or have the pool reap idle connections sooner (for example with ActiveRecord'sidle_timeout).
Lock wait timeouts (error 1205) still do not trigger failover (PR #234).
- a query that runs longer than
-
Declared
bigdecimalandloggeras runtime dependencies, since Ruby no longer installs them by default from 3.4 (bigdecimal) and 4.0 (logger) on, and dropped the need forbase64and the fullcgilibrary. 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).
🐛 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). - 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).
- Fixed
iam_access_token_property_name,cluster_id, andbgd_idnot accepting YAML-typed (non-string) values fromdatabase.yml, such as a numericcluster_id(PR #209). - Fixed the block form of
pg'sexec,query,exec_params, andexec_preparednot working throughWrapperPgConnection. The wrapper now yields the result to the block, clears it when the block returns, and returns the block's value, matchingpg(PR #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).
- 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).
- Fixed several ActiveRecord error-handling gaps: a
nilconnection is now recognized as a connection error; apgIAM authentication failure is classified as a connection error rather thanActiveRecord::NoDatabaseError;trilogyschema errors are identified correctly; andpingandclosenow match the underlying driver's behavior (PR #228).