Skip to content

AWS Advanced Ruby Driver Wrapper - v1.1.0

Latest

Choose a tag to compare

@aaron-congo aaron-congo released this 05 Nov 23:46
· 6 commits to main since this release

[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_auth plugin 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 okta plugin code (PR #215).
  • 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, PR #225).
  • Support for the 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).
  • 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_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).
  • 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_storage for 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 (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).

  • 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).

🐛 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, and bgd_id not accepting YAML-typed (non-string) values from database.yml, such as a numeric cluster_id (PR #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).
  • 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 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).