aws_advanced_ruby_driver_wrapper 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab8433b9c38b4c70ea438830ccc3d870bdd56141e5be9ad28e309aad7852074
-  data.tar.gz: bfc31bb5bbd87b1a3bb2ee416cc0208b79bd15c9e92422266822cc5a0904b0f5
+  metadata.gz: 6da8d07797b41d2bef7c26ac10bff8a3fcf6050d098344d3e850cf80d88305a9
+  data.tar.gz: 2f17adb4cca840143bacbf16056d67748f12204f22a5beb71ddb8bdc445aca3e
 SHA512:
-  metadata.gz: f321a9d2942e5cef6eada081baa62f5cedc42b906b8f991ab42bb9ee55bd6323381b0aa781090427e1f4d9b5a1c6ac9d2e32aadf0e2d4dfd476dc57ef34217d1
-  data.tar.gz: d6125a87b85478e47d4f851ff7c9d7a0a6aa6a14806575e6b77df86bff38f458c516497bc3c458abd0ccc66937fb1de1f77164d64c324bed60ee1786f7e7035d
+  metadata.gz: dc3f77408c42d2a2dde71cce86af1c0bb294380b6e7c679c51118e0fd2383f4d677e95d77521cbe974bf3c584e5f7af7b65244834a0489034d7ab9541982dcc6
+  data.tar.gz: fcfaa69564b9abfeed8095e5995a9893a636def8ea0f8c1ad471bbcf69a0f36f7593090b42f76083556c7ee834350238bc73c8e090408572ccf78b8a01ee858f

data/CHANGELOG.md

@@ -3,7 +3,22 @@ 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.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 +35,5 @@ 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

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)

data/lib/aws_advanced_ruby_driver_wrapper/active_record/aws_postgresql_adapter.rb

@@ -17,39 +17,67 @@
 require 'active_record/connection_adapters/postgresql_adapter'
 require_relative '../postgresql'
 require_relative '../errors'
-require_relative '../utils/ar_constants'
+require_relative 'type_adapter_alias'
+require_relative 'aws_connection_handler'
+require_relative 'aws_action_cable_postgresql_support'
 
 module ActiveRecord
   module ConnectionAdapters
     class AwsPostgreSQLAdapter < PostgreSQLAdapter
-      ADAPTER_NAME = 'AwsPostgreSQL'
-
-      # ActiveRecord-only keys that should not be passed to the wrapper or native driver.
-      AR_ONLY_KEYS = (AwsAdvancedRubyDriverWrapper::Utils::AR_COMMON_KEYS + %i[advisory_locks schema_search_path]).freeze
-
       # ActiveRecord uses :username and :database, but the PG gem expects :user and :dbname.
       # The parent adapter translates these in @connection_parameters, but also strips
       # non-PG keys (including wrapper properties) via slice!. Since we rebuild from @config
       # to preserve wrapper properties, we need to redo this translation ourselves.
       AR_TO_PG_KEY_MAP = { username: :user, database: :dbname }.freeze
 
+      # The connection options PG accepts, the same set the parent adapter forwards.
+      PG_CONNECTION_KEYS = (PG::Connection.conndefaults_hash.keys + [:requiressl]).to_set.freeze
+
       def initialize(...)
         # Capture the full config before the parent's initialize strips it
         # down to only PG-recognized keys in @connection_parameters.
         super
         @connection_broken = false
-        # Store non-AR parameters in @wrapper_config.
-        wrapper_config = @config.compact.except(*AR_ONLY_KEYS)
+        wrapper_config = @config.compact
         # Remap ActiveRecord key names to PG gem key names.
         AR_TO_PG_KEY_MAP.each { |ar_key, pg_key| wrapper_config[pg_key] = wrapper_config.delete(ar_key) if wrapper_config.key?(ar_key) }
-        @wrapper_config = wrapper_config
+        # Keep only what PG or the wrapper understands. Every other key is an ActiveRecord setting,
+        # and PG rejects any connection option it does not recognize.
+        @wrapper_config = wrapper_config.select { |key, _| self.class.forwarded_key?(key) }
+      end
+
+      # @return [Boolean] whether the config key is passed on to the wrapper connection
+      def self.forwarded_key?(key)
+        PG_CONNECTION_KEYS.include?(key) ||
+          AwsAdvancedRubyDriverWrapper::PropertyDefinition.wrapper_property?(key) ||
+          AwsAdvancedRubyDriverWrapper::PropertyDefinition::KNOWN_PREFIXES.any? { |prefix| key.to_s.start_with?(prefix) }
       end
 
-      def adapter_name = ADAPTER_NAME
+      # Resolve native database types from the wrapped PostgreSQLAdapter, overriding only :datetime.
+      # PostgreSQLAdapter builds its type hash from two things: the shared NATIVE_DATABASE_TYPES
+      # constant and the per-class datetime_type class_attribute. Delegating to the parent keeps a
+      # single source of truth, but the parent reads *its own* datetime_type, so this adapter's
+      # datetime_type (e.g. :timestamptz) must be re-applied here or it is silently ignored and
+      # t.datetime columns are created as plain timestamp.
+      def self.native_database_types
+        superclass.native_database_types.merge(datetime: NATIVE_DATABASE_TYPES[datetime_type])
+      end
 
       # 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.
       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::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
 
       def connect
@@ -71,10 +99,23 @@ module ActiveRecord
         super
       end
 
+      # Used by db:drop, db:reset, db:test:prepare and db:purge. ActiveRecord disconnects its own
+      # connections first, but the topology monitor shared by this cluster's connections, and the Blue/Green
+      # status providers, keep their own connections to the database, and PostgreSQL refuses to drop a
+      # database other sessions are using.
+      def drop_database(name)
+        raw_connection.stop_topology_monitor
+        AwsAdvancedRubyDriverWrapper::Plugins::BlueGreen::BlueGreenPlugin.clean_up_providers
+        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
+          # 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)

data/lib/aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias.rb

@@ -0,0 +1,61 @@
+# 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'
+
+module AwsAdvancedRubyDriverWrapper
+  # ActiveRecord's adapter-specific type registry (ActiveRecord::Type) keys every type
+  # registration and lookup by the *config adapter name*. The wrapped adapters register nothing of
+  # their own: they rely entirely on the vanilla PostgreSQL/Mysql2 adapters, which register their
+  # OID / native types under adapter: :postgresql and adapter: :mysql2. A lookup for an
+  # :aws_postgresql / :aws_mysql2 connection would therefore find none of them and raise
+  # "Unknown type" for things like :interval, :point, array/range columns, or MySQL's
+  # :unsigned_integer.
+  #
+  # Rather than copy the parent's registrations (which misses types registered after the adapter
+  # loads, needs a duplicate guard, and reaches into the registry's private internals), alias the
+  # wrapper adapter names to their parents inside the registry's own register/add_modifier/lookup.
+  # Every registration and every lookup — including the ones ActiveRecord routes through
+  # Type.adapter_name_from — passes through the registry, so normalizing the adapter there makes the
+  # wrapped adapters resolve the exact same types as the vanilla ones, for all current and future
+  # types, across Rails 7.2–8.1.
+  #
+  # Side effect: in an app that uses BOTH a plain postgresql and an aws_postgresql connection, a
+  # 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
+
+    # Prepended onto ActiveRecord::Type::AdapterSpecificRegistry. Normalizing the adapter in lookup
+    # covers both the framework path and a direct Type.lookup(..., adapter: :aws_postgresql); any
+    # type registered explicitly for a wrapper adapter lands under the parent's key.
+    module RegistryAlias
+      def register(type_name, klass = nil, adapter: nil, **, &)
+        super(type_name, klass, adapter: ADAPTER_ALIASES.fetch(adapter, adapter), **, &)
+      end
+
+      def add_modifier(options, klass, adapter: nil, **args)
+        super(options, klass, adapter: ADAPTER_ALIASES.fetch(adapter, adapter), **args)
+      end
+
+      def lookup(symbol, *, adapter: nil, **)
+        super(symbol, *, adapter: ADAPTER_ALIASES.fetch(adapter, adapter), **)
+      end
+    end
+  end
+end
+
+ActiveRecord::Type::AdapterSpecificRegistry.prepend(AwsAdvancedRubyDriverWrapper::TypeAdapterAlias::RegistryAlias)

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/driver_dialect.rb

@@ -115,6 +115,11 @@ module AwsAdvancedRubyDriverWrapper
         raise NotImplementedError
       end
 
+      # Releases a connection inherited from the parent process after a fork, without telling the
+      # server: the parent still owns the session. Garbage collection or process exit in the child
+      # must not end it.
+      def abandon_connection(connection); end
+
       def sql_state(_exception)
         nil
       end

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/mysql_driver_dialect.rb

@@ -131,6 +131,16 @@ module AwsAdvancedRubyDriverWrapper
         logger.error("Failed to close MySQL connection: #{e.message}")
       end
 
+      # With automatic_close off, mysql2 invalidates the socket instead of sending COM_QUIT when
+      # the client is collected, leaving the parent's session open.
+      def abandon_connection(connection)
+        return if connection.nil? || connection.closed?
+
+        connection.automatic_close = false
+      rescue StandardError => e
+        logger.debug("Failed to abandon MySQL connection: #{e.message}")
+      end
+
       def sql_state(exception)
         return nil unless exception.respond_to?(:sql_state)
 

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/pg_driver_dialect.rb

@@ -162,6 +162,16 @@ module AwsAdvancedRubyDriverWrapper
         logger.error("Failed to close PostgreSQL connection: #{e.message}")
       end
 
+      # Points the socket at /dev/null, so the Terminate message libpq sends when the connection
+      # is finished or collected never reaches the server.
+      def abandon_connection(connection)
+        return if connection.nil? || connection.finished?
+
+        connection.socket_io.reopen(IO::NULL)
+      rescue StandardError => e
+        logger.debug("Failed to abandon PostgreSQL connection: #{e.message}")
+      end
+
       def sql_state(exception)
         return nil unless exception.is_a?(::PG::Error) && exception.result
 

data/lib/aws_advanced_ruby_driver_wrapper/monitoring/cluster_topology_monitor.rb

@@ -131,6 +131,16 @@ module AwsAdvancedRubyDriverWrapper
         @instance_monitors_writer_conn.close
       end
 
+      def abandon_connections
+        @monitoring_connection.abandon
+        @instance_monitors_writer_conn.abandon
+        driver_dialect = @service_container.dialect_service.driver_dialect
+        @instance_monitor_connections.each_pair do |host, conn|
+          driver_dialect.abandon_connection(conn)
+          @instance_monitor_connections.delete(host)
+        end
+      end
+
       private
 
       # Main monitoring loop.

data/lib/aws_advanced_ruby_driver_wrapper/monitoring/monitor.rb

@@ -73,6 +73,20 @@ module AwsAdvancedRubyDriverWrapper
 
       def close; end
 
+      # Detaches this monitor in a forked child. Its thread did not survive the fork and its
+      # connections still belong to the parent, so the thread reference is dropped and the
+      # connections are abandoned rather than closed: closing them would end the parent's sessions.
+      def release_after_fork
+        @stop_flag.make_true
+        @thread = nil
+        @state.set(MonitorState::STOPPED)
+        abandon_connections
+      end
+
+      # Releases connections inherited from the parent process without closing them on the server.
+      # Subclasses that hold connections override this.
+      def abandon_connections; end
+
       private
 
       def run

data/lib/aws_advanced_ruby_driver_wrapper/monitoring/monitor_connection.rb

@@ -52,6 +52,12 @@ module AwsAdvancedRubyDriverWrapper
       def close
         set(nil)
       end
+
+      # Releases a connection inherited across a fork without closing it on the server. The reference
+      # is dropped too, so a later close or set cannot reach the parent's session.
+      def abandon
+        @driver_dialect.abandon_connection(@connection.get_and_set(nil))
+      end
     end
   end
 end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/blue_green_plugin.rb

@@ -130,6 +130,16 @@ module AwsAdvancedRubyDriverWrapper
           PROVIDERS.each_key { |k| PROVIDERS.delete(k)&.stop }
         end
 
+        # Forgets the providers inherited by a forked child so the child starts its own on first use.
+        # A provider that fails to release is still forgotten, and the rest are released.
+        def self.release_providers_after_fork
+          PROVIDERS.each_key do |key|
+            PROVIDERS.delete(key)&.release_after_fork
+          rescue StandardError => e
+            AwsAdvancedRubyDriverWrapper.logger.warn("Failed to release Blue/Green status provider #{key} after fork: #{e.message}")
+          end
+        end
+
         private
 
         def route_connect(host_info, driver_props, is_initial_connection, pipeline_callable, is_internal: false)

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/status_monitor.rb

@@ -338,6 +338,10 @@ module AwsAdvancedRubyDriverWrapper
           @event.reset
         end
 
+        def abandon_connections
+          @connection.abandon
+        end
+
         private
 
         def attempt_open_connection

data/lib/aws_advanced_ruby_driver_wrapper/plugins/blue_green/status_provider.rb

@@ -93,6 +93,11 @@ module AwsAdvancedRubyDriverWrapper
           @monitors.each_value { |m| m&.stop }
         end
 
+        # Detaches the monitors inherited by a forked child without closing the parent's connections.
+        def release_after_fork
+          @monitors.each_value { |m| m&.release_after_fork }
+        end
+
         def log_switchover_final_summary
           return unless switchover_finalized?
 

data/lib/aws_advanced_ruby_driver_wrapper/plugins/secrets_manager_plugin.rb

@@ -79,6 +79,12 @@ module AwsAdvancedRubyDriverWrapper
           storage_service.clear(SECRETS_MANAGER_CACHE_NAME)
         end
 
+        # Forgets fetches inherited by a forked child. A fetch running at fork time lost its thread,
+        # so its future never resolves and would otherwise be returned to every later fetch for its key.
+        def release_pending_refreshes_after_fork
+          @pending_refreshes.clear
+        end
+
         # The secret's value depends on which secret is read, from which region and endpoint, and
         # with which AWS credentials, so all of them are part of the key. Connections that differ in
         # any of them neither share a cached secret nor wait on each other's fetch.
@@ -244,7 +250,9 @@ module AwsAdvancedRubyDriverWrapper
           else
             Concurrent::Promises.future_on(:io) { fetch_and_store_secret(nil, credentials) }
           end
-        future.value!(SYNC_FETCH_TIMEOUT_SEC)
+        # value! returns nil instead of raising when the timeout elapses; a completed fetch always
+        # returns an entry or raises.
+        future.value!(SYNC_FETCH_TIMEOUT_SEC) || raise(Timeout::Error)
       rescue Concurrent::CancelledOperationError, Timeout::Error
         raise Errors::SecretsManagerAuthError,
               "Timed out fetching secret after #{SYNC_FETCH_TIMEOUT_SEC}s"

data/lib/aws_advanced_ruby_driver_wrapper/postgresql.rb

@@ -224,6 +224,14 @@ module AwsAdvancedRubyDriverWrapper
 
     alias finish close
 
+    # Stops the background topology monitor of this connection's cluster, which closes the connections it
+    # holds to the database it was started for. The next connection that needs topology starts a new one.
+    # PostgreSQL refuses to drop a database that other sessions are connected to, so this has to happen
+    # before dropping the database the monitor was started for.
+    def stop_topology_monitor
+      @service_container.host_service.host_list_provider&.stop_monitor
+    end
+
     # Resets the connection through the pipeline and returns this wrapper, so the reset connection stays
     # usable through it. The driver's own reset tears down and re-establishes the underlying socket, which
     # clears any server-side session state, so the tracked session state is reset to match.

data/lib/aws_advanced_ruby_driver_wrapper/services/monitor_service.rb

@@ -14,6 +14,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require 'concurrent'
 require_relative '../monitoring/monitor_state'
 require_relative '../logging'
 require_relative '../utils/storage/sliding_expiration_cache'
@@ -36,7 +37,7 @@ module AwsAdvancedRubyDriverWrapper
       def initialize(event_publisher:)
         @caches = {}
         @lock = Mutex.new
-        @running = true
+        @running = Concurrent::AtomicBoolean.new(true)
         @cleanup_thread = start_cleanup_thread
         event_publisher.subscribe(
           self,
@@ -112,7 +113,7 @@ module AwsAdvancedRubyDriverWrapper
       end
 
       def shutdown(grace_period:)
-        @running = false
+        @running.make_false
         begin
           @cleanup_thread&.wakeup
         rescue ThreadError
@@ -122,6 +123,24 @@ module AwsAdvancedRubyDriverWrapper
         stop_and_remove_all
       end
 
+      # Resets this service in a forked child. Monitor threads do not survive a fork, so the inherited
+      # monitors are detached (keeping the parent's connections open) and forgotten, letting
+      # run_if_absent start live ones. A monitor that fails to detach is still forgotten. The cleanup
+      # thread is restarted unless it is still alive, so calling this again does not start a second one.
+      def restart_after_fork
+        @lock.synchronize { @caches.values }.each do |container|
+          container.cache.entries.each_key do |key|
+            container.cache.remove(key)&.release_after_fork
+          rescue StandardError => e
+            logger.warn("Failed to release monitor #{key} after fork: #{e.message}")
+          end
+        end
+        return if @cleanup_thread&.alive?
+
+        @running.make_true
+        @cleanup_thread = start_cleanup_thread
+      end
+
       # Processes events from the event publisher.
       # @param event [Event] the event to process.
       def process_event(event)
@@ -142,7 +161,7 @@ module AwsAdvancedRubyDriverWrapper
 
       def start_cleanup_thread
         thread = Thread.new do
-          while @running
+          while @running.true?
             sleep(CLEANUP_INTERVAL_SEC)
             run_cleanup
           end

data/lib/aws_advanced_ruby_driver_wrapper/utils/events/batching_event_publisher.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'concurrent'
 require_relative '../../logging'
 
 module AwsAdvancedRubyDriverWrapper
@@ -23,10 +24,11 @@ module AwsAdvancedRubyDriverWrapper
       # Batches deduplicate events via Set semantics (eql?/hash).
       #
       # Public API:
-      #   subscribe(subscriber, event_classes) — register for event types
-      #   unsubscribe(subscriber, event_classes) — deregister
-      #   publish(event) — deliver immediate or queue batched
-      #   release_resources — stop background thread
+      #   subscribe(subscriber, event_classes) - register for event types
+      #   unsubscribe(subscriber, event_classes) - deregister
+      #   publish(event) - deliver immediate or queue batched
+      #   release_resources - stop background thread
+      #   restart_after_fork - restart background thread in a forked child
       class BatchingEventPublisher
         include Logging
 
@@ -37,7 +39,7 @@ module AwsAdvancedRubyDriverWrapper
           @subscribers = {}
           @event_queue = Set.new
           @lock = Mutex.new
-          @running = true
+          @running = Concurrent::AtomicBoolean.new(true)
           @thread = start_publishing_thread
         end
 
@@ -70,7 +72,7 @@ module AwsAdvancedRubyDriverWrapper
         end
 
         def release_resources
-          @lock.synchronize { @running = false }
+          @running.make_false
           begin
             @thread&.wakeup
           rescue ThreadError
@@ -79,11 +81,20 @@ module AwsAdvancedRubyDriverWrapper
           @thread&.join(@message_interval_sec)
         end
 
+        # Restarts the publishing thread in a forked child, where it no longer runs. A thread that is
+        # still alive is kept, so calling this again does not start a second one.
+        def restart_after_fork
+          return if @thread&.alive?
+
+          @running.make_true
+          @thread = start_publishing_thread
+        end
+
         private
 
         def start_publishing_thread
           thread = Thread.new do
-            while @lock.synchronize { @running }
+            while @running.true?
               sleep(@message_interval_sec)
               send_messages
             end

data/lib/aws_advanced_ruby_driver_wrapper/utils/storage/storage_service.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'concurrent'
 require_relative 'expiration_cache'
 require_relative '../../logging'
 require_relative '../events/data_access_event'
@@ -34,7 +35,8 @@ module AwsAdvancedRubyDriverWrapper
           @caches = {}
           @event_publisher = event_publisher
           @lock = Mutex.new
-          @running = true
+          @running = Concurrent::AtomicBoolean.new(true)
+          @cleanup_interval = cleanup_interval
           @cleanup_thread = start_cleanup_thread(cleanup_interval)
         end
 
@@ -107,6 +109,12 @@ module AwsAdvancedRubyDriverWrapper
           fetch_cache!(name).remove(key)
         end
 
+        # @param name [Symbol] cache name.
+        # @return [Boolean] whether a cache is registered under the name
+        def registered?(name)
+          @lock.synchronize { @caches.key?(name) }
+        end
+
         # Clears all items for a given name.
         # @param name [Symbol] registered cache name.
         def clear(name)
@@ -127,7 +135,7 @@ module AwsAdvancedRubyDriverWrapper
 
         # Stops the cleanup thread.
         def shutdown
-          @running = false
+          @running.make_false
           begin
             @cleanup_thread&.wakeup
           rescue ThreadError
@@ -136,6 +144,15 @@ module AwsAdvancedRubyDriverWrapper
           @cleanup_thread&.join(5)
         end
 
+        # Restarts the cleanup thread in a forked child, where it no longer runs. A thread that is
+        # still alive is kept, so calling this again does not start a second one.
+        def restart_after_fork
+          return if @cleanup_thread&.alive?
+
+          @running.make_true
+          @cleanup_thread = start_cleanup_thread(@cleanup_interval)
+        end
+
         private
 
         def fetch_cache!(name)
@@ -147,7 +164,7 @@ module AwsAdvancedRubyDriverWrapper
 
         def start_cleanup_thread(interval)
           thread = Thread.new do
-            while @running
+            while @running.true?
               sleep(interval)
               remove_expired_items
             end

data/lib/aws_advanced_ruby_driver_wrapper/version.rb

@@ -15,5 +15,5 @@
 #  limitations under the License.
 
 module AwsAdvancedRubyDriverWrapper
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/aws_advanced_ruby_driver_wrapper.rb

@@ -73,6 +73,38 @@ module AwsAdvancedRubyDriverWrapper
     Services::HostService.clear_id_cache
   end
 
+  # Runs in a forked child (see ForkHook). Only the forking thread survives a fork, so every background
+  # thread is gone and the inherited monitors look alive but never refresh. The monitors and Blue/Green
+  # providers are forgotten without closing their connections, which the parent still uses, Secrets
+  # Manager fetches that were in flight are forgotten, and the shared services restart their threads.
+  # Cached data such as topology stays valid and is kept.
+  def self.after_fork
+    Plugins::BlueGreen::BlueGreenPlugin.release_providers_after_fork
+    Plugins::SecretsManagerPlugin.release_pending_refreshes_after_fork if defined?(Plugins::SecretsManagerPlugin)
+    return unless defined?(Services::CoreServices)
+
+    Services::CoreServices.monitor_service.restart_after_fork
+    Services::CoreServices.event_publisher.restart_after_fork
+    Services::CoreServices.storage_service.restart_after_fork
+  end
+
+  # Process._fork is the single entry point for Kernel#fork, Process.fork and IO.popen('-'), so
+  # hooking it covers every way an application server or job runner forks a worker. An error in the
+  # child is logged rather than raised: raising here would fail the application's own fork call.
+  module ForkHook
+    def _fork
+      pid = super
+      if pid.zero?
+        begin
+          AwsAdvancedRubyDriverWrapper.after_fork
+        rescue StandardError => e
+          AwsAdvancedRubyDriverWrapper.logger.error("Failed to reset the wrapper's background services after fork: #{e.message}")
+        end
+      end
+      pid
+    end
+  end
+
   def self.release_resources(grace_period_sec: 5)
     require_relative 'aws_advanced_ruby_driver_wrapper/services/service_utility'
     Services::CoreServices.monitor_service.shutdown(grace_period: grace_period_sec)
@@ -88,6 +120,8 @@ end
 
 at_exit { AwsAdvancedRubyDriverWrapper.shutdown }
 
+Process.singleton_class.prepend(AwsAdvancedRubyDriverWrapper::ForkHook)
+
 # Register adapters with ActiveRecord via a lazy-load hook so the require order between this file and
 # ActiveRecord does not matter. The block runs the first time ActiveRecord::Base is referenced, whether
 # ActiveRecord is loaded before or after this file. The register call is itself lazy — each adapter file
@@ -101,6 +135,8 @@ end
 
 if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
   ActiveSupport.on_load(:active_record) do
+    require_relative 'aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias'
+
     ActiveRecord::ConnectionAdapters.register(
       'aws_postgresql',
       'ActiveRecord::ConnectionAdapters::AwsPostgreSQLAdapter',
@@ -114,3 +150,5 @@ if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
     )
   end
 end
+
+require_relative 'aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias' if defined?(ActiveRecord)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws_advanced_ruby_driver_wrapper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -44,8 +44,11 @@ files:
 - THIRD-PARTY-LICENSES
 - aws_advanced_ruby_driver_wrapper.gemspec
 - lib/aws_advanced_ruby_driver_wrapper.rb
+- lib/aws_advanced_ruby_driver_wrapper/active_record/aws_action_cable_postgresql_support.rb
+- lib/aws_advanced_ruby_driver_wrapper/active_record/aws_connection_handler.rb
 - lib/aws_advanced_ruby_driver_wrapper/active_record/aws_mysql2_adapter.rb
 - lib/aws_advanced_ruby_driver_wrapper/active_record/aws_postgresql_adapter.rb
+- lib/aws_advanced_ruby_driver_wrapper/active_record/type_adapter_alias.rb
 - lib/aws_advanced_ruby_driver_wrapper/custom_configuration.rb
 - lib/aws_advanced_ruby_driver_wrapper/db_dialects/aurora_mysql_dialect.rb
 - lib/aws_advanced_ruby_driver_wrapper/db_dialects/aurora_pg_dialect.rb
@@ -152,7 +155,6 @@ files:
 - lib/aws_advanced_ruby_driver_wrapper/services/service_utility.rb
 - lib/aws_advanced_ruby_driver_wrapper/services/session_state_service.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/accessible_regions.rb
-- lib/aws_advanced_ruby_driver_wrapper/utils/ar_constants.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/aurora_topology_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/aws_credentials_utils.rb
 - lib/aws_advanced_ruby_driver_wrapper/utils/connection_config.rb

data/lib/aws_advanced_ruby_driver_wrapper/utils/ar_constants.rb

@@ -1,25 +0,0 @@
-# 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.
-
-module AwsAdvancedRubyDriverWrapper
-  module Utils
-    # ActiveRecord-only keys that should not be passed to the wrapper or native driver.
-    AR_COMMON_KEYS = %i[
-      adapter pool checkout_timeout idle_timeout reaping_frequency
-      variables prepared_statements encoding reconnect socket flags
-    ].freeze
-  end
-end