aws_advanced_ruby_driver_wrapper 1.0.1 → 1.1.0

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/mysql2_driver_dialect.rb

@@ -0,0 +1,129 @@
+# 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
+    # How the mysql2 driver is called. The MySQL grammar and what every MySQL driver shares are
+    # inherited.
+    class Mysql2DriverDialect < MysqlDriverDialect
+      # Every mysql2 call that talks to the server. A call that is not listed here is handed straight
+      # to the driver, bypassing the plugin pipeline.
+      #
+      # Not listed, because libmysql answers them without talking to the server: escape, the row and
+      # column counts, last_id, affected_rows, info, warning_count, thread_id, server_info,
+      # session_track, and the connection's own settings.
+      NETWORK_BOUND_METHODS = (COMMON_NETWORK_BOUND_METHODS | Set[
+        RubyMethod::CONNECTION_QUERY.name,
+        RubyMethod::CONNECTION_ASYNC_RESULT.name,
+        RubyMethod::CONNECTION_SELECT_DB.name,
+        RubyMethod::CONNECTION_MORE_RESULTS.name,
+        RubyMethod::CONNECTION_NEXT_RESULT.name,
+        RubyMethod::CONNECTION_STORE_RESULT.name,
+        RubyMethod::CONNECTION_ABANDON_RESULTS.name,
+        RubyMethod::CONNECTION_SET_SERVER_OPTION.name,
+        RubyMethod::RESULT_EACH.name,
+        RubyMethod::RESULT_FREE.name
+      ]).freeze
+
+      def name
+        'mysql2'
+      end
+
+      def connect(host_info, config)
+        ::Mysql2::Client.new(**prepare_connect_config(host_info, config))
+      end
+
+      def execute(connection, sql)
+        raise Mysql2::Error, 'MySQL client is not connected' if connection.nil? || connection.closed?
+
+        connection.query(sql)
+      end
+
+      def execute_with_params(connection, sql, params)
+        raise Mysql2::Error, 'MySQL client is not connected' if connection.nil? || connection.closed?
+
+        stmt = connection.prepare(sql)
+        result = stmt.execute(*params)
+        # Everything the caller needs must be read off the statement before the ensure closes its
+        # handle. A SELECT result is bound to the handle, so materialize its rows now - otherwise a
+        # later iteration (e.g. SqlRunner calling #to_a) raises "Statement handle already closed".
+        # A non-SELECT statement returns nil, and its affected-row count must come from the statement
+        # too: once the handle is closed the connection-level mysql_affected_rows returns its -1 error
+        # sentinel and mysql2 raises. So return that count for #affected_rows to hand back.
+        result.is_a?(::Mysql2::Result) ? result.to_a : stmt.affected_rows
+      ensure
+        stmt&.close
+      end
+
+      # mysql2 binds a blob parameter as raw binary bytes.
+      def binary_param(bytes)
+        bytes.b
+      end
+
+      # mysql2 hands back a blob column as a string that only needs its encoding forced to binary.
+      def read_binary(value)
+        value.b
+      end
+
+      # A prepared statement (execute_with_params) hands back its own affected-row count, since the
+      # connection-level count is unreadable once the statement handle is closed. A plain
+      # connection.query (execute) leaves nil, so the count is read off the connection instead.
+      def affected_rows(connection, result)
+        result.is_a?(Integer) ? result : connection.affected_rows.to_i
+      end
+
+      # mysql2 has no RETURNING clause, so the generated id is read from the connection afterwards.
+      def insert_returning_id(connection, sql, params, _id_column)
+        execute_with_params(connection, sql, params)
+        id = connection.last_id
+        id&.positive? ? id : nil
+      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
+
+      # mysql2 reports the version it learned when it connected, so reading it costs no round trip.
+      def executable_comment_version(connection)
+        return nil if connection.nil?
+
+        info = connection.server_info
+        info.is_a?(Hash) ? info[:id] : nil
+      rescue StandardError => e
+        logger.debug { "The MySQL server version could not be read: #{e.message}" }
+        nil
+      end
+
+      def sql_state(exception)
+        return nil unless exception.respond_to?(:sql_state)
+
+        exception.sql_state
+      end
+
+      def network_bound_methods
+        NETWORK_BOUND_METHODS
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/mysql_driver_dialect.rb

@@ -19,84 +19,22 @@ require_relative '../host/connection_string_host_list_provider'
 
 module AwsAdvancedRubyDriverWrapper
   module DriverDialects
+    # What every MySQL driver shares: the server's SQL grammar, and the connection options and
+    # connection calls the MySQL drivers name alike. A driver's own dialect subclasses this and adds
+    # how the driver itself is called.
     class MysqlDriverDialect
       include DriverDialect
 
-      # Every mysql2 call that talks to the server. A call that is not listed here is handed straight
-      # to the driver, bypassing the plugin pipeline.
-      #
-      # Not listed, because libmysql answers them without talking to the server: escape, the row and
-      # column counts, last_id, affected_rows, info, warning_count, thread_id, server_info,
-      # session_track, and the connection's own settings.
-      NETWORK_BOUND_METHODS = (COMMON_NETWORK_BOUND_METHODS | Set[
-        RubyMethod::CONNECTION_QUERY.name,
-        RubyMethod::CONNECTION_ASYNC_RESULT.name,
-        RubyMethod::CONNECTION_SELECT_DB.name,
-        RubyMethod::CONNECTION_MORE_RESULTS.name,
-        RubyMethod::CONNECTION_NEXT_RESULT.name,
-        RubyMethod::CONNECTION_STORE_RESULT.name,
-        RubyMethod::CONNECTION_ABANDON_RESULTS.name,
-        RubyMethod::CONNECTION_SET_SERVER_OPTION.name,
-        RubyMethod::RESULT_EACH.name,
-        RubyMethod::RESULT_FREE.name
-      ]).freeze
-
-      def connect(host_info, config)
-        ::Mysql2::Client.new(**prepare_connect_config(host_info, config))
-      end
-
-      def execute(connection, sql)
-        raise Mysql2::Error, 'MySQL client is not connected' if connection.nil? || connection.closed?
-
-        connection.query(sql)
-      end
-
-      def execute_with_params(connection, sql, params)
-        raise Mysql2::Error, 'MySQL client is not connected' if connection.nil? || connection.closed?
-
-        stmt = connection.prepare(sql)
-        result = stmt.execute(*params)
-        # Everything the caller needs must be read off the statement before the ensure closes its
-        # handle. A SELECT result is bound to the handle, so materialize its rows now - otherwise a
-        # later iteration (e.g. SqlRunner calling #to_a) raises "Statement handle already closed".
-        # A non-SELECT statement returns nil, and its affected-row count must come from the statement
-        # too: once the handle is closed the connection-level mysql_affected_rows returns its -1 error
-        # sentinel and mysql2 raises. So return that count for #affected_rows to hand back.
-        result.is_a?(::Mysql2::Result) ? result.to_a : stmt.affected_rows
-      ensure
-        stmt&.close
+      def database_engine
+        :mysql
       end
 
-      # mysql2 uses +?+ placeholders, so the SQL is already in its native form.
+      # MySQL uses +?+ placeholders, so the SQL is already in its native form.
       def translate_placeholders(sql)
         sql
       end
 
-      # mysql2 binds a blob parameter as raw binary bytes.
-      def binary_param(bytes)
-        bytes.b
-      end
-
-      # mysql2 hands back a blob column as a string that only needs its encoding forced to binary.
-      def read_binary(value)
-        value.b
-      end
-
-      # A prepared statement (execute_with_params) hands back its own affected-row count, since the
-      # connection-level count is unreadable once the statement handle is closed. A plain
-      # connection.query (execute) leaves nil, so the count is read off the connection instead.
-      def affected_rows(connection, result)
-        result.is_a?(Integer) ? result : connection.affected_rows.to_i
-      end
-
-      # mysql2 has no RETURNING clause, so the generated id is read from the connection afterwards.
-      def insert_returning_id(connection, sql, params, _id_column)
-        execute_with_params(connection, sql, params)
-        id = connection.last_id
-        id&.positive? ? id : nil
-      end
-
-      # mysql2 upserts with ON DUPLICATE KEY UPDATE, reading the incoming row from VALUES().
+      # MySQL upserts with ON DUPLICATE KEY UPDATE, reading the incoming row from VALUES().
       def upsert_clause(_conflict_columns, update_columns)
         assignments = update_columns.map { |column| "#{column} = VALUES(#{column})" }.join(', ')
         "ON DUPLICATE KEY UPDATE #{assignments}"
@@ -131,26 +69,6 @@ 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)
-
-        exception.sql_state
-      end
-
-      def network_bound_methods
-        NETWORK_BOUND_METHODS
-      end
-
       def prepare_connect_config(host_info, config)
         cfg = {}
         config.each { |k, v| cfg[k] = v }
@@ -163,9 +81,9 @@ module AwsAdvancedRubyDriverWrapper
         :username
       end
 
+      # Read, write and connect timeouts (in seconds) make a query or a close on a dead socket raise a
+      # timeout error rather than hang. With mysql2 they also keep it from segfaulting.
       def apply_monitoring_defaults(driver_props)
-        # mysql2 read_timeout / write_timeout (in seconds) ensure that queries and closes
-        # on a dead socket raise Mysql2::Error::TimeoutError instead of segfaulting.
         driver_props[:read_timeout] ||= DEFAULT_MONITORING_TIMEOUT_SEC
         driver_props[:write_timeout] ||= DEFAULT_MONITORING_TIMEOUT_SEC
         driver_props[:connect_timeout] ||= DEFAULT_MONITORING_TIMEOUT_SEC

data/lib/aws_advanced_ruby_driver_wrapper/driver_dialects/pg_driver_dialect.rb

@@ -85,6 +85,14 @@ module AwsAdvancedRubyDriverWrapper
         RubyMethod::CONNECTION_LO_TRUNCATE.name
       ]).freeze
 
+      def name
+        'pg'
+      end
+
+      def database_engine
+        :postgresql
+      end
+
       def connect(host_info, config)
         ::PG::Connection.new(**prepare_connect_config(host_info, config))
       end
@@ -182,6 +190,16 @@ module AwsAdvancedRubyDriverWrapper
         NETWORK_BOUND_METHODS
       end
 
+      # libpq separates the socket target (+hostaddr+) from the TLS/IAM server name (+host+), so a pg
+      # connection can be pinned to a specific instance IP while still verifying the certificate
+      # against - and generating an IAM token for - the original hostname. Blue/Green substitute
+      # routing uses this so a pinned connection reaches the intended instance regardless of what DNS
+      # resolves to mid-switchover, and still passes +verify-full+ whatever the CA source - instead of
+      # connecting to a raw IP (certificate-name mismatch) or falling back to the hostname (DNS risk).
+      def props_pinned_to_ip(driver_props, ip)
+        driver_props.dup.tap { |props| props[:hostaddr] = ip }
+      end
+
       def prepare_connect_config(host_info, config)
         cfg = {}
         config.each { |k, v| cfg[k] = v }

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

@@ -506,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