aws_advanced_ruby_driver_wrapper 1.0.0 → 1.1.0

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/trilogy_driver_dialect.rb

@@ -0,0 +1,118 @@
+# 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 'mysql_driver_dialect'
+
+module AwsAdvancedRubyDriverWrapper
+  module DriverDialects
+    # The trilogy driver speaks the same MySQL protocol and grammar as mysql2, so everything that
+    # depends only on the server is inherited. What is overridden is how the driver itself is called.
+    class TrilogyDriverDialect < MysqlDriverDialect
+      # The trilogy calls that talk to the server and that failover should cover. The failover, Blue/Green
+      # and Custom Endpoint plugins subscribe to exactly these, and a call that is not listed here and
+      # reaches the client's method_missing is handed straight to the driver.
+      #
+      # Not listed, because trilogy answers them without talking to the server: escape, closed?,
+      # more_results_exist?, the counts and ids of the last statement, server_status, in_transaction?,
+      # server_version, the query flags and timeouts, and discard!, which only lets go of the socket.
+      # A Trilogy::Result is read off the wire in full before it is returned, so reading its rows
+      # never talks to the server either.
+      #
+      # Not listed although it talks to the server: ping, as for mysql2. ActiveRecord pings to check
+      # that a connection is still alive and rescues the driver's own errors to answer false and
+      # reconnect; failing over inside that check would raise a wrapper error out of it instead.
+      NETWORK_BOUND_METHODS = (COMMON_NETWORK_BOUND_METHODS | Set[
+        RubyMethod::CONNECTION_QUERY.name,
+        RubyMethod::CONNECTION_CHANGE_DB.name,
+        RubyMethod::CONNECTION_SELECT_DB.name,
+        RubyMethod::CONNECTION_NEXT_RESULT.name,
+        RubyMethod::CONNECTION_ABANDON_RESULTS.name,
+        RubyMethod::CONNECTION_SET_SERVER_OPTION.name
+      ]).freeze
+
+      # A placeholder, or a quoted string or identifier, matched whole so that a question mark inside
+      # one is not taken for a placeholder. Quotes inside are escaped by a backslash or by doubling.
+      PLACEHOLDER_OR_QUOTED = /'(?:[^'\\]|\\.|'')*'|"(?:[^"\\]|\\.|"")*"|`(?:[^`]|``)*`|\?/m
+
+      def name
+        'trilogy'
+      end
+
+      # Trilogy.new stores the options it is given and writes to them, so it is handed a hash of its
+      # own, which prepare_connect_config builds afresh on every call.
+      def connect(host_info, config)
+        ::Trilogy.new(prepare_connect_config(host_info, config))
+      end
+
+      # Trilogy returns rows as arrays. They are keyed by column name here, as mysql2 returns them,
+      # because that is the shape the database dialects read their rows in.
+      def execute(connection, sql)
+        connection.query(sql).each_hash.to_a
+      end
+
+      # Trilogy has no prepared statements, so each parameter is written into the SQL as a literal,
+      # quoted and escaped by the connection the way ActiveRecord quotes its own binds for trilogy.
+      # Only the types the wrapper binds in its own queries are accepted.
+      def execute_with_params(connection, sql, params)
+        placeholders = sql.scan(PLACEHOLDER_OR_QUOTED).count('?')
+        raise ArgumentError, "SQL has #{placeholders} placeholders for #{params.size} parameters" unless placeholders == params.size
+
+        literals = params.map { |value| literal(connection, value) }
+        bound_sql = sql.gsub(PLACEHOLDER_OR_QUOTED) { |token| token == '?' ? literals.shift : token }
+
+        execute(connection, bound_sql)
+      end
+
+      # Every reply from the server carries its status flags, and trilogy keeps the last of them, so
+      # whether a transaction is open is known without inferring it from the SQL.
+      def reported_in_transaction(connection)
+        return nil if closed?(connection)
+
+        connection.in_transaction?
+      end
+
+      # discard! closes the socket without sending COM_QUIT or a TLS close notify, leaving the
+      # parent's session open.
+      def abandon_connection(connection)
+        return if connection.nil? || connection.closed?
+
+        connection.discard!
+      rescue StandardError => e
+        logger.debug("Failed to abandon MySQL connection: #{e.message}")
+      end
+
+      def network_bound_methods
+        NETWORK_BOUND_METHODS
+      end
+
+      # trilogy names the TLS CA certificate option +ssl_ca+, where mysql2 names it +sslca+.
+      def tls_ca_property_key
+        :ssl_ca
+      end
+
+      private
+
+      def literal(connection, value)
+        case value
+        when nil then 'NULL'
+        when Integer then value.to_s
+        when String then "'#{connection.escape(value)}'"
+        else raise ArgumentError, "Cannot bind a #{value.class} parameter for trilogy"
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/errors/error_handler.rb

@@ -41,6 +41,22 @@ module AwsAdvancedRubyDriverWrapper
         raise NotImplementedError
       end
 
+      # Whether the driver reported +error+ as a database error, i.e. it carries a SQLSTATE (or, for
+      # trilogy, a MySQL error code). This is not a strict server-vs-client split: mysql2 also reports
+      # SQLSTATE HY000 for client-side failures such as a lost connection. Used by the Blue/Green status
+      # monitor to tell database errors from other exceptions. A driver whose errors carry no SQLSTATE
+      # (trilogy) overrides this to classify by its numeric error code.
+      def database_error?(error)
+        !@driver_dialect.sql_state(error).nil?
+      end
+
+      # Whether +error+ is a schema/syntax error (SQLSTATE class '42': missing table, unknown column,
+      # parse error, missing routine). The Blue/Green status monitor reads this as "the status
+      # table/function is not there", i.e. NOT_CREATED. Default is SQLSTATE-based; trilogy overrides.
+      def schema_error?(error)
+        @driver_dialect.sql_state(error)&.start_with?('42') || false
+      end
+
       private
 
       def extract_sql_state(error)

data/lib/aws_advanced_ruby_driver_wrapper/errors/mysql_error_handler.rb

@@ -29,7 +29,8 @@ module AwsAdvancedRubyDriverWrapper
         2006, # CR_SERVER_GONE_ERROR (server has gone away)
         2013, # CR_SERVER_LOST (lost connection during query)
         2026, # CR_SSL_CONNECTION_ERROR
-        2055  # CR_SERVER_LOST_EXTENDED (lost connection with state info)
+        2055, # CR_SERVER_LOST_EXTENDED (lost connection with state info)
+        4031  # ER_CLIENT_INTERACTION_TIMEOUT (MySQL 8.0.24+ closed a connection that exceeded wait_timeout)
       ].freeze
 
       def initialize(driver_dialect)
@@ -68,12 +69,16 @@ module AwsAdvancedRubyDriverWrapper
       private
 
       def connection_error_network?(error)
-        return false unless defined?(Mysql2::Error::ConnectionError) && error.is_a?(Mysql2::Error::ConnectionError)
+        return false unless defined?(Mysql2::Error) && error.is_a?(Mysql2::Error)
 
-        error_number = error.respond_to?(:error_number) ? error.error_number : nil
-        return true if error_number && NETWORK_ERROR_CODES.include?(error_number)
+        NETWORK_ERROR_CODES.include?(error.error_number) || read_timeout?(error)
+      end
 
-        false
+      # mysql2 raises Mysql2::Error::TimeoutError for two unrelated conditions. A client-side read_timeout
+      # carries no error number, and mysql2 invalidates the socket before raising it, so the connection is
+      # unusable. A lock wait timeout (1205) is a server error on a healthy connection and is excluded.
+      def read_timeout?(error)
+        error.is_a?(Mysql2::Error::TimeoutError) && error.error_number.nil?
       end
     end
   end

data/lib/aws_advanced_ruby_driver_wrapper/errors/trilogy_error_handler.rb

@@ -0,0 +1,127 @@
+# 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 'error_handler'
+
+module AwsAdvancedRubyDriverWrapper
+  module Errors
+    # Trilogy errors carry no SQLSTATE, so they are classified by class and by the server's error code.
+    class TrilogyErrorHandler
+      include ErrorHandler
+
+      LOGIN_ERROR_CODES = Set[
+        1044, # ER_DBACCESS_DENIED_ERROR
+        1045  # ER_ACCESS_DENIED_ERROR
+      ].freeze
+      READ_ONLY_ERROR_CODES = Set[1290, 1836].freeze
+      LOCK_WAIT_TIMEOUT_ERROR_CODE = 1205
+
+      # MySQL error codes whose SQLSTATE is class '42' (schema/syntax). trilogy carries no SQLSTATE,
+      # so the Blue/Green monitor's "is the status table/function gone?" question is answered from
+      # the code instead - the same codes libmysql would map to a '42xxx' state for mysql2.
+      SCHEMA_ERROR_CODES = Set[
+        1051, # ER_BAD_TABLE_ERROR
+        1054, # ER_BAD_FIELD_ERROR
+        1064, # ER_PARSE_ERROR
+        1109, # ER_UNKNOWN_TABLE
+        1142, # ER_TABLEACCESS_DENIED_ERROR
+        1146, # ER_NO_SUCH_TABLE
+        1305, # ER_SP_DOES_NOT_EXIST
+        1370  # ER_PROCACCESS_DENIED_ERROR
+      ].freeze
+
+      # A protocol violation raised while receiving the authentication response. Unlike a clean
+      # ER_ACCESS_DENIED_ERROR (1045), trilogy raises this from its C extension as a codeless
+      # Trilogy::QueryError (error_code nil, not a ConnectionError), so it is matched by its message
+      # marker rather than by code. The server aborting the auth handshake this way means the
+      # credential was not accepted, so for login-retry purposes it is a login error.
+      AUTH_PROTOCOL_VIOLATION = 'trilogy_auth_recv'
+      PROTOCOL_VIOLATION_MARKER = 'TRILOGY_PROTOCOL_VIOLATION'
+
+      def initialize(driver_dialect)
+        @driver_dialect = driver_dialect
+      end
+
+      # Every Trilogy::ConnectionError except those that do not mean the server is unreachable: rejected
+      # credentials, a lock wait timeout, an authentication plugin trilogy refuses (an IAM token without
+      # enable_cleartext_plugin) and a connection the application closed. Read and write timeouts count,
+      # as they do for mysql2.
+      def network_error?(error)
+        check_cause_chain(error) { |_, current| network_failure?(current) }
+      end
+
+      def network_error_by_sql_state?(_sql_state)
+        false
+      end
+
+      def login_error?(error)
+        check_cause_chain(error) do |_, current|
+          LOGIN_ERROR_CODES.include?(error_code(current)) || auth_protocol_violation?(current)
+        end
+      end
+
+      def login_error_by_sql_state?(_sql_state)
+        false
+      end
+
+      def read_only_error?(error)
+        check_cause_chain(error) { |_, current| READ_ONLY_ERROR_CODES.include?(error_code(current)) }
+      end
+
+      def read_only_error_by_sql_state?(_sql_state, error_code = nil)
+        READ_ONLY_ERROR_CODES.include?(error_code)
+      end
+
+      # Whether the driver reported +error+ as a database error. trilogy carries no SQLSTATE, so this
+      # classifies by the presence of the server's numeric error code: a code is present for a server
+      # error and absent for a client/transport failure (a Trilogy::BaseConnectionError, a read/write
+      # timeout, the codeless auth protocol violation).
+      def database_error?(error)
+        !error_code(error).nil?
+      end
+
+      def schema_error?(error)
+        SCHEMA_ERROR_CODES.include?(error_code(error))
+      end
+
+      private
+
+      def network_failure?(error)
+        return false unless defined?(::Trilogy::ConnectionError) && error.is_a?(::Trilogy::ConnectionError)
+        return false if error.is_a?(::Trilogy::ConnectionClosed) || error.is_a?(::Trilogy::AuthPluginError)
+
+        code = error_code(error)
+        !LOGIN_ERROR_CODES.include?(code) && code != LOCK_WAIT_TIMEOUT_ERROR_CODE
+      end
+
+      def error_code(error)
+        error.respond_to?(:error_code) ? error.error_code : nil
+      end
+
+      # True for a codeless protocol violation raised during the auth handshake. trilogy surfaces a
+      # rejected/aborted credential exchange as a Trilogy::QueryError carrying "TRILOGY_PROTOCOL_VIOLATION
+      # (trilogy_auth_recv)" with no MySQL error code, so it is identified by message rather than code.
+      # Scoped to the auth phase so a mid-session protocol error is not misread as a login failure.
+      def auth_protocol_violation?(error)
+        return false unless defined?(::Trilogy::Error) && error.is_a?(::Trilogy::Error)
+        return false unless error_code(error).nil?
+
+        message = error.message.to_s
+        message.include?(PROTOCOL_VIOLATION_MARKER) && message.include?(AUTH_PROTOCOL_VIOLATION)
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/errors.rb

@@ -51,6 +51,7 @@ module AwsAdvancedRubyDriverWrapper
     end
 
     class IamAuthError < AwsError; end
+    class SamlAuthError < AwsError; end
     class SecretsManagerAuthError < AwsError; end
     class PluginConflictError < AwsError; end
     class BlueGreenTimeoutError < AwsError; end

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.
@@ -496,6 +506,7 @@ module AwsAdvancedRubyDriverWrapper
       end
 
       def stored_hosts
+        # Explicitly unregistered: a monitor reading its own data must not keep itself alive.
         storage_service.get(TOPOLOGY_CACHE_NAME, @cluster_id, register_access: false)
       end
 

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/mysql.rb

@@ -20,6 +20,7 @@ require_relative '../aws_advanced_ruby_driver_wrapper'
 require_relative 'utils/connection_config_parser'
 require_relative 'utils/sql_encoding'
 require_relative 'services/service_utility'
+require_relative 'utils/telemetry/telemetry_factory'
 require_relative 'ruby_method'
 require_relative 'errors'
 
@@ -34,13 +35,16 @@ module AwsAdvancedRubyDriverWrapper
     def initialize(**)
       ensure_mysql2!
       config = Utils::ConnectionConfigParser.parse(:mysql2, **)
-      @service_container = Services::ServiceUtility.create_standard_container(config)
-      @service_container.host_service.refresh_host_list
-      @async_conn = nil
-      @async_sql = nil
-      @last_sql = nil
-      conn_service = @service_container.connection_service
-      @service_container.plugin_manager.connect(conn_service.initial_host_info, conn_service.driver_props, true)
+      telemetry_factory = Utils::Telemetry::TelemetryFactory.new(config.wrapper_props)
+      telemetry_factory.in_context("#{self.class.name}.new", Utils::Telemetry::TraceLevel::TOP_LEVEL, record_result: true) do
+        @service_container = Services::ServiceUtility.create_standard_container(config, telemetry_factory:)
+        @service_container.host_service.refresh_host_list
+        @async_conn = nil
+        @async_sql = nil
+        @last_sql = nil
+        conn_service = @service_container.connection_service
+        @service_container.plugin_manager.connect(conn_service.initial_host_info, conn_service.driver_props, true)
+      end
     end
 
     # Explicitly define critical methods (bypass method_missing to avoid method_missing overhead)
@@ -53,6 +57,7 @@ module AwsAdvancedRubyDriverWrapper
     # What is remembered is the copy of the SQL that plugins inspect, made once here rather than on
     # every call that is handed it later. The driver is sent the SQL as the application wrote it.
     def query(sql, options = {})
+      ensure_connected!
       inspected = Utils::SqlEncoding.inspectable(sql)
       result = pm.execute(RubyMethod::CONNECTION_QUERY, current_conn, ->(*a) { current_conn.query(*a) }, sql, options,
                           sql: inspected)
@@ -76,10 +81,14 @@ module AwsAdvancedRubyDriverWrapper
     end
 
     def ping
+      return false if current_conn.nil?
+
       pm.execute(RubyMethod::CONNECTION_PING, current_conn, -> { current_conn.ping })
     end
 
     def close
+      return if current_conn.nil?
+
       pm.execute(RubyMethod::CONNECTION_CLOSE, current_conn, -> { current_conn.close })
     end
 
@@ -143,8 +152,7 @@ module AwsAdvancedRubyDriverWrapper
     BOUNDED_TO_ASYNC = Set[:abandon_results!].freeze
 
     def method_missing(method_name, *args, **kwargs, &)
-      conn = current_conn
-      raise NoMethodError, 'Connection not initialized' if conn.nil?
+      conn = ensure_connected!
       raise NoMethodError, "undefined method `#{method_name}' for #{self.class}" unless conn.respond_to?(method_name)
 
       method_key = "connection.#{method_name}"
@@ -197,6 +205,16 @@ module AwsAdvancedRubyDriverWrapper
       @service_container.connection_service.current_connection
     end
 
+    # Guards the entry points that reach for the current connection directly (the query path and
+    # method_missing). Without a live connection AR expects the driver's own "not connected" error,
+    # which it translates to a connection error; a bare NoMethodError on nil would not be recognized.
+    def ensure_connected!
+      conn = current_conn
+      raise Mysql2::Error::ConnectionError, 'MySQL client is not connected' if conn.nil?
+
+      conn
+    end
+
     def pm
       @service_container.plugin_manager
     end

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

@@ -19,6 +19,7 @@ require_relative '../../logging'
 require_relative '../../ruby_method'
 require_relative '../../property_definition'
 require_relative '../../utils/rds_utils'
+require_relative 'drop_blue_connections_marker'
 require_relative 'phase'
 require_relative 'role'
 require_relative 'status'
@@ -32,6 +33,14 @@ module AwsAdvancedRubyDriverWrapper
 
         BLUE_GREEN_NAME = :blue_green
 
+        # Storage partition for the drop-blue-connections marker, kept separate from BLUE_GREEN_NAME so
+        # it can outlive the status cache's TTL. The marker is stored once per switchover and never
+        # re-stamped, so a connection that sits idle longer than the status cache's TTL must still find
+        # the marker on its next use. A long TTL is safe: a marker only matches connections opened before
+        # its own switchover, and a later switchover overwrites it.
+        DROP_MARKER_NAME = :blue_green_drop_marker
+        DROP_MARKER_TTL_SEC = 86_400
+
         # When present in wrapper_props, internal_connect calls bypass BG routing.
         # Used by BG monitoring connections to avoid being intercepted by their own plugin.
         BG_SKIP_ROUTING_KEY = :'bg.skip_routing'
@@ -43,6 +52,13 @@ module AwsAdvancedRubyDriverWrapper
 
         PROVIDERS = Concurrent::Map.new
 
+        # Storage key, within the DROP_MARKER_NAME cache, under which the drop-blue-connections marker
+        # for a deployment is kept. DROP_MARKER_NAME is a separate partition from the status cache, so
+        # the marker survives both the status cache's TTL and the provider's reset_context_when_completed.
+        def self.drop_marker_key(bgd_id)
+          "#{bgd_id}::drop_blue_connections_marker"
+        end
+
         def initialize(service_container, props = ::Concurrent::Map.new)
           @service_container = service_container
           @wrapper_props = props
@@ -52,7 +68,17 @@ module AwsAdvancedRubyDriverWrapper
           @start_time_ns = Concurrent::AtomicReference.new(0)
           @end_time_ns = Concurrent::AtomicReference.new(0)
 
+          # Per-connection drop-blue-connections state. Each wrapper client has its own plugin instance,
+          # so these describe this connection: when it was opened, the host it was opened to, and the
+          # identity of the last marker it was checked against.
+          @drop_blue_connections = PropertyDefinition::BG_DROP_BLUE_CONNECTIONS.get_bool(props)
+          @connection_open_time_ns = nil
+          @connect_time_host = nil
+          @checked_drop_marker_id = nil
+          @pending_stale_marker_id = nil
+
           service_container.storage_service.register(BLUE_GREEN_NAME, ttl: 3600)
+          service_container.storage_service.register(DROP_MARKER_NAME, ttl: DROP_MARKER_TTL_SEC)
 
           network_methods = service_container.dialect_service.driver_dialect.network_bound_methods
           @subscribed_methods = (Set['connect', 'internal_connect'] | network_methods).freeze
@@ -61,7 +87,12 @@ module AwsAdvancedRubyDriverWrapper
         attr_reader :subscribed_methods
 
         def connect(host_info, driver_props, is_initial_connection, pipeline_callable)
-          route_connect(host_info, driver_props, is_initial_connection, pipeline_callable, is_internal: false)
+          conn = route_connect(host_info, driver_props, is_initial_connection, pipeline_callable, is_internal: false)
+          # Only this client's own connect describes its connection. Internal connects (topology
+          # monitoring, KMS metadata reads) run through this same plugin instance but open separate
+          # connections, so they must not overwrite this connection's open time, host, or marker latches.
+          record_connection_open(host_info)
+          conn
         end
 
         def internal_connect(host_info, driver_props, wrapper_props, is_initial_connection, pipeline_callable)
@@ -79,7 +110,21 @@ module AwsAdvancedRubyDriverWrapper
 
             return pipeline_callable.call if CLOSING_METHODS.include?(method_name)
 
+            # Read the status before the stale check. The provider stores the active drop marker before
+            # it writes the POST/COMPLETED status, so reading status first closes the race where a stale
+            # check sees a still-pending marker and the COMPLETED early return below then skips re-checking
+            # the now-active marker: if the switchover has completed, the check below sees the active marker.
             @bg_status = storage_service.get(BLUE_GREEN_NAME, @bgd_id)
+
+            # Invalidate a connection opened to the old blue environment before a confirmed switchover,
+            # so the failover plugin reconnects through BG routing instead of serving a stale read. This
+            # runs before the NOT_CREATED/COMPLETED early return below, because after the switchover the
+            # status is COMPLETED (then NOT_CREATED) and would otherwise skip the check entirely.
+            if stale_blue_connection?
+              invalidate_stale_blue_connection
+              return pipeline_callable.call
+            end
+
             if @bg_status.nil? || @bg_status.current_phase == Phase::NOT_CREATED || @bg_status.current_phase == Phase::COMPLETED
               return pipeline_callable.call
             end
@@ -95,20 +140,24 @@ module AwsAdvancedRubyDriverWrapper
             result = nil
 
             while routing && result.nil?
-              result = routing.apply(method_name, @wrapper_props, storage_service)
+              result = routing.apply(method_name, @wrapper_props, storage_service, telemetry_factory: @service_container.telemetry_factory)
 
               next unless result.nil?
 
               @bg_status = storage_service.get(BLUE_GREEN_NAME, @bgd_id)
-              if @bg_status.nil?
-                @end_time_ns.set(nano_time)
-                return pipeline_callable.call
-              end
+              break if @bg_status.nil?
+
               routing = @bg_status.execute_routing.find { |r| r.match?(current_host, host_role) }
             end
 
             @end_time_ns.set(nano_time)
-            result.nil? ? pipeline_callable.call : result
+            return result unless result.nil?
+
+            # The call may have been held through the switchover (e.g. suspended during IN_PROGRESS and
+            # released at POST, which has no execute routing). Re-check whether this connection is now a
+            # stale blue connection before running it, so a held call is not run against retired blue.
+            invalidate_stale_blue_connection if stale_blue_connection?
+            pipeline_callable.call
           ensure
             @end_time_ns.set(nano_time) if @start_time_ns.get.positive? && @end_time_ns.get.zero?
           end
@@ -130,6 +179,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)
@@ -192,6 +251,65 @@ module AwsAdvancedRubyDriverWrapper
           end
         end
 
+        # Remembers when this connection was opened and the host it was opened to, so a later switchover
+        # can tell whether it is a blue connection that predates the switchover.
+        def record_connection_open(host_info)
+          return unless @drop_blue_connections
+
+          @connection_open_time_ns = nano_time
+          @connect_time_host = host_info&.host&.downcase
+          # A (re)connect produces a fresh connection (e.g. after failover): reset the per-connection
+          # marker latches so this new incarnation re-evaluates the current marker from a clean slate
+          # instead of inheriting the retired connection's checked/pending state.
+          @checked_drop_marker_id = nil
+          @pending_stale_marker_id = nil
+        end
+
+        # Whether this connection should be invalidated because it was opened to the old blue environment
+        # before a now-confirmed switchover. The marker is read on every call so a later switchover's
+        # marker is noticed. A marker that does not apply to this connection is latched immediately and
+        # never re-examined; a marker that does apply is only latched once #invalidate_stale_blue_connection
+        # confirms the close, so a transient close failure leaves the connection to be invalidated again on
+        # its next use instead of silently serving stale reads for the rest of its life.
+        def stale_blue_connection?
+          return false unless @drop_blue_connections
+
+          marker = storage_service.get(DROP_MARKER_NAME, self.class.drop_marker_key(@bgd_id), register_access: false)
+          return false unless marker.is_a?(DropBlueConnectionsMarker) && marker.active?
+          return false if marker.id == @checked_drop_marker_id
+
+          if marker.stale?(@connect_time_host, @connection_open_time_ns)
+            @pending_stale_marker_id = marker.id
+            true
+          else
+            # This connection does not predate the switchover and never will against this marker (markers
+            # are immutable), so latch it now to skip re-reading the marker on every future call.
+            @checked_drop_marker_id = marker.id
+            false
+          end
+        end
+
+        # Closes the connection directly through the driver dialect rather than the pipeline's close
+        # method. Going through the pipeline would set the failover plugin's @closed_explicitly, which
+        # would stop it from reconnecting. Closing it out from under the pipeline instead lets the
+        # failover plugin (if enabled) see a connection closed that it did not close, fail over, and
+        # raise FailoverSuccessError; without failover the driver raises its closed-connection error.
+        def invalidate_stale_blue_connection
+          logger.info do
+            "[bgd_id: '#{@bgd_id}'] Invalidating a connection to #{@connect_time_host} from the old blue environment " \
+              'retired by a Blue/Green switchover. It will fail over (or raise a closed-connection error) on this use.'
+          end
+
+          conn = @service_container.connection_service.current_connection
+          @service_container.dialect_service.driver_dialect.close_connection(conn) unless conn.nil?
+          # Only now that the close is confirmed do we latch the marker as handled. If the close raised
+          # and was swallowed below, the marker stays unlatched so the next use retries the invalidation
+          # rather than serving a stale read from retired blue for the rest of the connection's life.
+          @checked_drop_marker_id = @pending_stale_marker_id
+        rescue StandardError => e
+          logger.debug { "[bgd_id: '#{@bgd_id}'] Failed to invalidate stale blue connection: #{e.class}: #{e.message}" }
+        end
+
         def storage_service
           @service_container.storage_service
         end