tina4ruby 3.13.94 → 3.13.96

data/lib/tina4/database.rb

@@ -145,6 +145,111 @@ module Tina4
       stripped
     end
 
+    # Blank out string literals, quoted identifiers and BOTH comment forms so a
+    # keyword search sees only real SQL.
+    #
+    # Blanks are spaces of the SAME LENGTH (newlines preserved), so offsets and
+    # line structure still line up with the original — the scrubbed copy is only
+    # ever used to LOOK at the SQL, never to execute it.
+    #
+    # MEASURED 2026-08-01 on a real 150-row SQLite table with the 100-row cap in
+    # force. The old detector was
+    #   `sql.upcase.split("--")[0].include?("LIMIT")`
+    # and each of these returned ALL 150 ROWS instead of 100:
+    #
+    #   SELECT * FROM t WHERE label != 'LIMIT' ORDER BY id     literal
+    #   SELECT * FROM t ORDER BY id -- LIMIT 5                 line comment
+    #   SELECT * FROM t ORDER BY id /* LIMIT 5 */              block comment
+    #   SELECT id, label AS rate_limit FROM t                  identifier
+    #
+    # A silently uncapped read of a whole table is the production incident the
+    # cap exists to prevent, and an ordinary column name was enough to cause it.
+    # Ported from the Python/Node master (same design, same answers).
+    def self.scrub_sql_text(sql)
+      return sql if sql.nil? || sql.empty?
+
+      out = +""
+      i = 0
+      n = sql.length
+      while i < n
+        ch = sql[i]
+        nxt = i + 1 < n ? sql[i + 1] : ""
+
+        if ch == "'" || ch == '"'
+          quote = ch
+          out << " "
+          i += 1
+          while i < n
+            if sql[i] == quote
+              # A doubled quote ('' / "") is an ESCAPED quote inside the
+              # literal, not its end — blank both and keep going.
+              if i + 1 < n && sql[i + 1] == quote
+                out << "  "
+                i += 2
+                next
+              end
+              out << " "
+              i += 1
+              break
+            end
+            out << (sql[i] == "\n" ? "\n" : " ")
+            i += 1
+          end
+          next
+        end
+
+        if ch == "-" && nxt == "-"
+          while i < n && sql[i] != "\n"
+            out << " "
+            i += 1
+          end
+          next
+        end
+
+        if ch == "/" && nxt == "*"
+          out << "  "
+          i += 2
+          while i < n && !(sql[i] == "*" && i + 1 < n && sql[i + 1] == "/")
+            out << (sql[i] == "\n" ? "\n" : " ")
+            i += 1
+          end
+          if i < n
+            out << "  "
+            i += 2
+          end
+          next
+        end
+
+        out << ch
+        i += 1
+      end
+      out
+    end
+
+    # True when the statement ENDS with its own LIMIT clause.
+    #
+    # Anchored to the END on purpose: a bare "contains LIMIT" test also matches a
+    # LIMIT inside a SUBQUERY, where the OUTER statement still needs its cap.
+    # This is tina4-php's SqlNormalizerTrait::hasTrailingLimit regex, ported
+    # verbatim so all four frameworks answer identically. It accepts a numeric
+    # value, ?/$1/:name/%s placeholders, MySQL's `LIMIT a, b` comma form, and a
+    # trailing OFFSET.
+    #
+    # Literals, quoted identifiers and comments are scrubbed before matching —
+    # see .scrub_sql_text for the measured failures that motivate it.
+    VALUE_TOKEN = '(?:\d+|\?|\$\d+|:\w+|%s)'
+    TRAILING_LIMIT_RE = /
+      \bLIMIT\s+#{VALUE_TOKEN}
+      (?:\s*,\s*#{VALUE_TOKEN})?
+      (?:\s+OFFSET\s+#{VALUE_TOKEN})?
+      \s*;?\s*\z
+    /ix.freeze
+
+    def self.has_trailing_limit?(sql)
+      return false if sql.nil? || sql.empty?
+      TRAILING_LIMIT_RE.match?(scrub_sql_text(sql))
+    end
+
     # Static factory — cross-framework consistency: Database.create(url)
     def self.create(url, username: "", password: "", pool: nil)
       new(url, username: username.empty? ? nil : username,
@@ -310,7 +415,7 @@ module Tina4
       # native toggle (default ON — see @autocommit in #initialize). The
       # framework-level commit in #autocommit_standalone_write covers drivers
       # that have no native setter.
-      @driver.autocommit = @autocommit if @driver.respond_to?(:autocommit=)
+      @driver.autocommit = @autocommit if driver_implements?(@driver, :autocommit=)
 
       Tina4::Log.info("Database connected: #{@driver_name}")
       @connect_error = nil
@@ -370,10 +475,18 @@ module Tina4
 
     # The connection string with any password stripped, so a raised error can name
     # the target without leaking a credential into a log or an HTTP 500 body.
+    #
+    # This used to carry its own regex, which was a SECOND redaction
+    # implementation next to DatabaseUrl#to_safe_string - and it leaked on two
+    # shapes, both measured 2026-08-02:
+    #   postgres://u:p@ss@h:5432/db  ->  postgres://u:***@ss@h:5432/db
+    #     because `([^:/@]+):[^@]*@` stops at the FIRST "@", so the tail of a
+    #     password containing an unencoded "@" survived into the message.
+    #   odbc:///DRIVER=...;PWD=<secret>  ->  returned VERBATIM, straight into
+    #     DatabaseConnectionError.
+    # There is now ONE redaction primitive. Do not add a second.
     def safe_connection_target
-      return '' if @connection_string.nil? || @connection_string.empty?
-
-      @connection_string.sub(%r{://([^:/@]+):[^@]*@}, '://\1:***@')
+      Tina4::DatabaseUrl.redact(@connection_string)
     end
 
     # ── Query Cache ──────────────────────────────────────────────
@@ -470,10 +583,43 @@ module Tina4
       sql = Tina4::Database.strip_trailing_semicolons(sql)
 
       effective_sql = sql
-      # Skip appending LIMIT if SQL already has one
-      has_limit = sql.upcase.split("--")[0].include?("LIMIT")
+      # Skip appending LIMIT if the statement already ENDS with its own.
+      #
+      # .has_trailing_limit? scrubs literals/identifiers/comments and anchors to
+      # the end. The old test was `sql.upcase.split("--")[0].include?("LIMIT")`,
+      # so `WHERE label != 'LIMIT'`, a `/* LIMIT 5 */` comment, or a column named
+      # rate_limit all read as "the caller supplied their own" and the cap was
+      # silently dropped — a full-table read (MEASURED: 150 of 150 rows).
+      has_limit = Tina4::Database.has_trailing_limit?(sql)
+      applied_limit = 0
+      # `limit: 0` means "no cap, give me everything" - the same reading as the
+      # Python master's `limit <= 0`. Ruby treats 0 as TRUTHY, so this used to
+      # fall through and append a literal `LIMIT 0`, returning ZERO rows where
+      # Python returned all of them for the identical call. fetch_all passes nil
+      # and was never affected, which is why it went unnoticed.
+      limit = nil if limit.is_a?(Numeric) && limit <= 0
       if limit && !has_limit
         effective_sql = drv.apply_limit(effective_sql, limit, offset)
+        applied_limit = limit
+      end
+
+      # COUNT PROBE: `count` is the TRUE total for the filter, not the number of
+      # rows this page returned.
+      #
+      # Ruby and Node used to populate count with records.length while Python
+      # and PHP populated it from a probe, so `db.fetch(sql).count` answered 20
+      # here and 250 there for one query against one table - and every paginated
+      # response built on it under-reported. MEASURED 2026-08-05 on a 250-row
+      # table read with limit=20: Ruby reported total 20 and 1 page against
+      # Python's 250 and 13.
+      #
+      # Only probed when WE appended the pagination. If no limit was applied
+      # (fetch_all, or the caller supplied their own LIMIT) the rows returned
+      # ARE the whole answer for this SQL, so records.length is already the true
+      # total and a second round-trip would buy nothing.
+      total = nil
+      if applied_limit.positive?
+        total = count_probe(drv, sql, params)
       end
 
       if @cache_enabled && !no_cache
@@ -486,13 +632,13 @@ module Tina4
         # fetch_direct RAISES on a SQL error (and captures @last_error), so a
         # failed read never reaches cache_set below — we never cache an empty
         # result produced by a buried failure.
-        result = fetch_direct(drv, effective_sql, params)
+        result = fetch_direct(drv, effective_sql, params, limit: applied_limit, offset: offset, total: total)
         cache_set(key, result)
         @cache_mutex.synchronize { @cache_misses += 1 }
         return result
       end
 
-      fetch_direct(drv, effective_sql, params)
+      fetch_direct(drv, effective_sql, params, limit: applied_limit, offset: offset, total: total)
     end
 
     # Fetch a single row (or nil).
@@ -559,7 +705,7 @@ module Tina4
       # — instead of probing a session sequence (lastval()) that returns nil or
       # a stale wrong id for a UUID table. Other engines (SQLite/MySQL/MSSQL/
       # Firebird) keep the generic build-then-last_insert_id path below.
-      if drv.respond_to?(:insert)
+      if driver_implements?(drv, :insert)
         result = drv.insert(table, data)
         autocommit_standalone_write(drv)
         # A driver that owns its insert (PostgreSQL, via RETURNING *) returns a
@@ -583,7 +729,7 @@ module Tina4
     # insert). Mirrors the Python master + PHP, whose write DatabaseResult carries
     # affected_rows/affectedRows; best-effort on drivers without a native count.
     def write_affected(drv, default = 0)
-      drv.respond_to?(:affected_rows) ? drv.affected_rows.to_i : default
+      driver_implements?(drv, :affected_rows) ? drv.affected_rows.to_i : default
     end
     private :write_affected
 
@@ -633,12 +779,36 @@ module Tina4
 
       if where_sql.empty?
         pk_columns = primary_key(table)
-        # Resolve each key column to whichever form the caller used (String or
-        # Symbol); nil marks one that is absent from the data.
+        # Resolve each key column to whichever form the caller used - String or
+        # Symbol, and in whatever CASE they typed; nil marks one that is absent.
+        #
+        # The engines disagree about identifier case BY DESIGN and always will:
+        # Firebird folds an unquoted identifier to UPPER, PostgreSQL folds it to
+        # LOWER, MySQL and SQLite preserve what was typed. Introspection hands
+        # back the ENGINE's spelling while `data` carries the caller's, so an
+        # exact match failed on whichever engine folds the other way. That is a
+        # case-sensitivity bug, not a Firebird quirk - Firebird merely made it
+        # visible first, because the shared write-path contract writes lower-case
+        # keys and Firebird reports upper-case ones.
+        #
+        # Deliberately does NOT downcase what introspection returns: that would
+        # special-case one engine and break a genuinely quoted mixed-case table.
+        # The WHERE below is still built from the ENGINE's column name (pk_columns);
+        # only the VALUE is looked up by the caller's key.
         pk_keys = pk_columns.map do |col|
-          if data.key?(col) then col
-          elsif data.key?(col.to_sym) then col.to_sym
+          folded = col.to_s.downcase
+          matches = data.keys.select { |k| k.to_s.downcase == folded }
+          if matches.length > 1
+            # Ambiguity is refused, never guessed - choosing wrong here writes
+            # the WHERE clause of an UPDATE.
+            raise ArgumentError,
+                  "update was given more than one key for the primary-key column " \
+                  "#{col.inspect}: #{matches.map(&:to_s).sort.inspect} " \
+                  "(table=#{table.inspect}). These differ only by case, so which one " \
+                  "identifies the row is ambiguous - pass exactly one, or pass an " \
+                  "explicit filter."
           end
+          matches.first
         end
         missing = pk_columns.each_with_index.reject { |_, i| pk_keys[i] }.map(&:first)
 
@@ -795,7 +965,19 @@ module Tina4
       begin
         drv.begin_transaction unless already_pinned
         begin
-          params_list.each { |params| drv.execute(sql, params) }
+          # ONE round-trip per CHUNK instead of one per ROW. Looping execute()
+          # here pays a full network round-trip for every row: 500 rows took
+          # 9848ms on PostgreSQL against 15.8ms as a single multi-row VALUES
+          # (625x), MySQL 216x, MSSQL 121x. build_batch_inserts returns an empty
+          # array for anything it cannot collapse safely - RETURNING, upserts,
+          # non-INSERT statements, ragged rows, Firebird - and the row-at-a-time
+          # loop then runs unchanged.
+          batched = SQLTranslator.build_batch_inserts(sql, params_list, get_database_type)
+          if batched.empty?
+            params_list.each { |params| drv.execute(sql, params) }
+          else
+            batched.each { |chunk_sql, chunk_params| drv.execute(chunk_sql, chunk_params) }
+          end
           drv.commit unless already_pinned
         rescue => e
           drv.rollback unless already_pinned
@@ -812,6 +994,11 @@ module Tina4
         nil
       end
 
+      # last_id stays the LAST inserted row's id. MySQL reports the FIRST id of
+      # a multi-row INSERT; its DRIVER normalises that at write time (the only
+      # place that knows both the first id and the row count), so get_last_id
+      # and this result always agree. Normalising here instead would
+      # double-apply.
       Tina4::DatabaseResult.new(
         [],
         affected_rows: params_list.length,
@@ -930,7 +1117,7 @@ module Tina4
       # v3.13.14 (#48): drivers that can resolve a schema/catalog-qualified
       # name ("gift_cards.gift_card", "dbo.widget", "attached.table") answer
       # directly; the rest fall back to a case-insensitive scan of tables.
-      return drv.table_exists?(table_name) if drv.respond_to?(:table_exists?)
+      return drv.table_exists?(table_name) if driver_implements?(drv, :table_exists?)
 
       tables.any? { |t| t.downcase == table_name.to_s.downcase }
     end
@@ -1048,10 +1235,52 @@ module Tina4
     # main query propagates (same contract as #execute). The cause is captured on
     # @last_error for #get_error before the re-raise — preferring the driver's own
     # last_error (when it exposes one, e.g. postgres) over the exception message.
-    def fetch_direct(drv, effective_sql, params)
+    # `limit:`/`offset:` are the pagination ACTUALLY APPLIED to this statement —
+    # `limit: 0` means "no cap was appended" (an explicit no-limit read, or SQL
+    # that carries its own trailing LIMIT). They were never passed before, so
+    # DatabaseResult#limit fell through to its constructor default and reported
+    # 10 on EVERY fetch whatever limit ran — the same stale v2 number the buried
+    # PHP row-cap test asserted as the cap, sitting one field away from the read
+    # path it fails to describe.
+    # The true row count for `sql`, ignoring the pagination we appended.
+    #
+    # BEST EFFORT BY DESIGN, and it must never mask a real failure: it runs
+    # BEFORE the main query and returns nil on any error, so the main query
+    # still runs and still raises loudly on bad SQL. A probe that swallowed the
+    # error AND the main query's would turn a typo into "no rows".
+    #
+    # nil (not 0) is the miss value. DatabaseResult then falls back to
+    # records.length, which is a true lower bound. Reporting 0 alongside 100
+    # real records - as a failed probe would - is simply false, and it is the
+    # same "envelope states a wrong number authoritatively" defect this whole
+    # change exists to remove.
+    #
+    # The closing paren goes on its OWN LINE. Appended inline, a trailing
+    # `-- comment` in the caller's SQL comments the paren out and the probe dies
+    # with "incomplete input". Postgres, MySQL, MSSQL and ODBC additionally
+    # require a name for the derived table; SQLite and Firebird do not, and
+    # Firebird rejects the `AS` keyword there - so the alias comes from the
+    # driver rather than being assumed.
+    def count_probe(drv, sql, params)
+      return nil unless driver_implements?(drv, :execute_query)
+
+      alias_name = driver_implements?(drv, :count_subquery_alias) ? drv.count_subquery_alias.to_s : ""
+      suffix = alias_name.empty? ? "" : " AS #{alias_name}"
+      rows = drv.execute_query("SELECT COUNT(*) AS tina4_total FROM (#{sql}\n)#{suffix}", params)
+      row = rows.is_a?(Array) ? rows.first : nil
+      return nil unless row.is_a?(Hash)
+
+      value = row["tina4_total"] || row[:tina4_total] || row["TINA4_TOTAL"] || row.values.first
+      value.nil? ? nil : value.to_i
+    rescue StandardError
+      nil
+    end
+
+    def fetch_direct(drv, effective_sql, params, limit: 0, offset: 0, total: nil)
       result = drv.execute_query(effective_sql, params)
       @last_error = nil
-      Tina4::DatabaseResult.new(result, sql: effective_sql, db: self)
+      Tina4::DatabaseResult.new(result, sql: effective_sql, db: self,
+                                limit: limit, offset: offset, count: total)
     rescue => e
       @last_error = driver_error_message(drv, e)
       raise
@@ -1075,7 +1304,7 @@ module Tina4
     # Prefer the driver's own last_error (postgres sets one) over str(e), so the
     # captured message matches what each engine surfaces; never blank.
     def driver_error_message(drv, error)
-      drv_err = drv.respond_to?(:last_error) ? drv.last_error : nil
+      drv_err = driver_implements?(drv, :last_error) ? drv.last_error : nil
       msg = drv_err || error.message
       msg = error.message if msg.nil? || msg.to_s.empty?
       msg || @last_error
@@ -1167,7 +1396,7 @@ module Tina4
     # lock (NOT via ensure_sequence_table, which would re-enter current_driver/
     # table_exists? and risk a nested touch).
     def sequence_next_sqlite(drv, seq_name, table, pk_column)
-      conn = drv.respond_to?(:connection) ? drv.connection : nil
+      conn = driver_implements?(drv, :connection) ? drv.connection : nil
       raise "get_next_id: SQLite driver has no live connection" if conn.nil?
 
       Tina4::Drivers::SqliteDriver.write_lock.synchronize do
@@ -1349,8 +1578,46 @@ module Tina4
       end
     end
 
+    # Stable identity of the DATABASE a cache entry came from.
+    #
+    # engine://host:port/database - and deliberately NOTHING else.
+    #
+    # WHY IT EXISTS: the key used to be sha256(sql + params) with nothing naming
+    # the connection, so on any SHARED backend two databases cross-served each
+    # other's rows. Two apps pointed at one Redis, or one app with a primary and
+    # an analytics connection, silently read each other's data. Identical SQL
+    # text across tenants is the COMMON case, not an edge case, so the collision
+    # was the normal outcome.
+    #
+    # WHY NO CREDENTIALS: a password in the key means every rotation silently
+    # cold-starts the cache, and a shared backend's key namespace is visible to
+    # every tenant of that backend - a secret must never be folded into it. The
+    # username is out for the same reason plus a second: two connections
+    # differing only by role read the SAME rows and should share the entry.
+    #
+    # WHY NOTHING PER-PROCESS: no pid, no object_id, no salt. Those would
+    # isolate the databases by accident and destroy the point of a shared cache,
+    # because no instance would ever hit another instance's entry.
+    def self.cache_identity(url)
+      parsed = Tina4::DatabaseUrl.new(url.to_s)
+      "#{parsed.engine}://#{parsed.host}:#{parsed.port}/#{parsed.database}"
+    rescue StandardError
+      # An unparseable connection string still needs a STABLE identity, and
+      # falling back to a constant would silently restore the cross-serving bug.
+      # The raw string is stable and distinct; it is only reached for a string
+      # the connection layer is about to reject anyway.
+      url.to_s
+    end
+    private_class_method :cache_identity
+
+    # Generate a cache key from DATABASE IDENTITY + SQL + params.
+    #
+    # The NUL separators keep the three parts from running together, so a table
+    # named after the tail of a database name cannot forge another database's
+    # key.
     def cache_key(sql, params)
-      Digest::SHA256.hexdigest(sql + params.to_s)
+      raw = "#{self.class.send(:cache_identity, @connection_string)}\x00#{sql}\x00#{params || []}"
+      Digest::SHA256.hexdigest(raw)
     end
 
     def cache_get(key)
@@ -1440,8 +1707,41 @@ module Tina4
       row.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
     end
 
+    # Did the driver actually OVERRIDE this, or is it inheriting the raising
+    # stub from Tina4::DatabaseAdapter?
+    #
+    # These call sites used to ask `respond_to?`. Including the contract module
+    # makes every driver respond to every contract method, so `respond_to?` can
+    # no longer tell "implemented" from "declared and not yet written" - and
+    # answering it wrongly turns a working path into a NotImplementedError.
+    #
+    # Methods outside the contract (affected_rows, last_error, connection) are
+    # not on the module at all, so this degrades to a plain respond_to? for them.
+    def driver_implements?(drv, name)
+      return false if drv.nil?
+      return Tina4::DatabaseAdapter.implemented_by?(drv, name) if
+        Tina4::DatabaseAdapter::CONTRACT.include?(name.to_s.chomp("=").chomp("?").to_sym)
+
+      drv.respond_to?(name)
+    end
+
     def detect_driver(conn)
-      case conn.to_s.downcase
+      # A real URL is decided by its SCHEME, through DatabaseUrl, which resolves
+      # aliases once and RAISES on a scheme it does not know.
+      #
+      # The substring matching below is kept only for connection strings that
+      # are not URLs at all (a bare "app.db" path). It used to handle
+      # everything, and its `else "sqlite"` meant an unrecognised URL did not
+      # fail - it quietly became SQLite. The app boots, writes to a local file,
+      # and nobody learns the real database was never reached. It also matched
+      # on substrings, so a postgres database named "mysqldata" could be
+      # detected as MySQL.
+      text = conn.to_s
+      if text.match?(/\A[a-zA-Z][a-zA-Z0-9+.-]*:/)
+        return Tina4::DatabaseUrl.new(text).engine
+      end
+
+      case text.downcase
       when /\.db$/, /\.sqlite/, /sqlite/
         "sqlite"
       when /postgres/, /^pg:/

data/lib/tina4/database_adapter.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Tina4
+  # The contract every database driver must satisfy.
+  #
+  # Feature 3 of the feature audit. Ruby had NO adapter interface: `Database`
+  # called four things on a driver and guarded the rest behind six `respond_to?`
+  # checks. The consequences, in order of severity:
+  #
+  # - A driver missing a method was discovered at runtime, on whichever engine
+  #   nobody exercised, and the guards meant the failure was often a SILENT SKIP
+  #   rather than an exception - which is worse than a crash.
+  # - Nothing told a contributor writing an eighth driver what to implement. The
+  #   answer was "read database.rb and infer", and it is 828 lines.
+  # - The audit could not compare Ruby's contract to the other three, because
+  #   Ruby did not have one. That was the finding.
+  #
+  # Measured against the shared contract (spec/fixtures/adapter_contract.json,
+  # byte-identical in all four), the seven drivers scored 9, 10 and 11 out of 20
+  # - three different levels of completeness, because each implemented whatever
+  # its facade path happened to need.
+  #
+  # Every method here raises. A driver that does not override one fails LOUDLY,
+  # at the point of the call, naming itself and the method - instead of being
+  # quietly skipped.
+  #
+  # == Migration in progress
+  #
+  # The owner's decision (2026-07-30) is that CRUD lives on the ADAPTER, matching
+  # PHP, Python and Node. Today Ruby's facade builds the SQL for fetch / insert /
+  # update / delete and calls the driver's +execute+, consulting +drv.insert+
+  # only when a driver chooses to own it (PostgreSQL does, via RETURNING *).
+  # Those methods are declared here so the gap is visible and countable; they are
+  # migrated driver by driver, each with its own test, rather than in one sweep.
+  #
+  # Until a driver overrides them, +Database+ keeps using its own path - see
+  # +Database#driver_implements?+, which asks whether the driver actually
+  # OVERRODE a method rather than whether it merely responds to it. That
+  # distinction is the whole point: including this module makes every driver
+  # respond to everything, so +respond_to?+ stopped being able to tell the
+  # difference.
+  module DatabaseAdapter
+    # Methods a driver MUST override. Kept as data so the conformance spec can
+    # read it instead of maintaining a second copy of the list.
+    # The REDESIGNED contract: only what genuinely differs per engine.
+    #
+    # CRUD (insert/update/delete), executeMany, fetchOne and DDL
+    # (create_table/add_column) are NOT here. They are composable above the
+    # adapter from execute + fetch + get_database_type, and Ruby was already
+    # doing exactly that in the facade - which is why Ruby's driver layer is
+    # 1335 LOC against PHP's 5823 for the same job. The first contract this row
+    # produced would have made Ruby write those seven more times; this one keeps
+    # the shape Ruby already had and asks the other three to adopt it.
+    CONTRACT = %i[
+      open close get_database_type
+      execute fetch
+      start_transaction commit rollback autocommit
+      get_tables get_columns table_exists
+      last_insert_id error
+    ].freeze
+
+    CONTRACT.each do |name|
+      define_method(name) do |*_args, **_kwargs, &_block|
+        raise NotImplementedError,
+              "#{self.class} does not implement ##{name}, which the Tina4 " \
+              "database adapter contract requires. See Tina4::DatabaseAdapter."
+      end
+    end
+
+    # == Bounding the connect
+    #
+    # A connect that can block forever hangs the whole application with NO log,
+    # no error and no signal. MEASURED here on Ruby 3.2.3 / Ubuntu 24.04.4
+    # against a real TCPServer that accepts the TCP connection and then never
+    # replies: pg, mysql2, tiny_tds AND fb all sat past 20 seconds and needed
+    # SIGKILL - `timeout`'s SIGTERM could not even be delivered, because the
+    # blocking work happens inside a C client that never yields to the
+    # interpreter. (A CLOSED port is a different thing entirely: it refuses in
+    # 0.00s and tests nothing.)
+    #
+    # ONE variable governs every driver whose connect crosses a network:
+    #
+    #   TINA4_DATABASE_CONNECT_TIMEOUT   seconds, default 10; <= 0 disables the
+    #                                    bound (unbounded, the old behaviour);
+    #                                    a non-number warns and falls back to 10
+    #
+    # Each driver applies it through its OWN native option - libpq
+    # connect_timeout, mysql2 connect_timeout, FreeTDS login_timeout, mongo
+    # connect_timeout - because only the C client can interrupt its own blocking
+    # socket work. Ruby's Timeout.timeout and Thread#join CANNOT: see
+    # Tina4::Drivers::FirebirdDriver.bound_reachability! for the measurement.
+    #
+    # There is deliberately NO outer Ruby timeout racing the native one. The
+    # native option is the ONLY timer; bounding_connect below merely TRANSLATES
+    # whatever the client raises into the one contract message, so the operator
+    # is never left holding a driver-worded error that names no variable. Where
+    # a driver cannot produce that message at all, its own file says so at the
+    # point of exclusion:
+    #
+    #   postgres  bounded + contract message   libpq connect_timeout
+    #   mysql     bounded + contract message   mysql2 connect_timeout
+    #   mssql     bounded + contract message   FreeTDS login_timeout
+    #   firebird  bounded to REACHABILITY only stdlib socket; the attach itself
+    #                                          cannot be bounded from Ruby
+    #   mongodb   bounded, NO message possible Client.new never fails
+    #   sqlite    n/a                          local file, no network peer
+    #   odbc      NOT bounded                  gem untestable here; see its file
+    CONNECT_TIMEOUT_VAR = "TINA4_DATABASE_CONNECT_TIMEOUT"
+    DEFAULT_CONNECT_TIMEOUT_SECONDS = 10
+
+    # Clock slack when deciding whether a failed connect was OUR bound expiring.
+    # A native bound of 10s is measured back as 9.998s often enough to matter,
+    # and without the slack the contract error would degrade into the raw driver
+    # error at random.
+    CONNECT_TIMEOUT_SLACK_SECONDS = 0.25
+
+    # Seconds to bound a connect by, or nil when the operator disabled the bound.
+    def self.connect_timeout_seconds
+      seconds = Tina4::Env.float(CONNECT_TIMEOUT_VAR, default: DEFAULT_CONNECT_TIMEOUT_SECONDS)
+      seconds.positive? ? seconds : nil
+    end
+
+    # Whole seconds for the native options that accept only an integer (libpq,
+    # libmysqlclient, FreeTDS). Rounds UP and never below 1: libpq reads
+    # connect_timeout=0 as "wait forever", so rounding 0.4 DOWN to 0 would
+    # silently disable the very bound being set.
+    def self.connect_timeout_whole_seconds
+      seconds = connect_timeout_seconds
+      seconds && [seconds.ceil, 1].max
+    end
+
+    # The one error a timed-out connect raises: it names the host, the port, the
+    # seconds actually spent, and the variable that tunes it.
+    def self.connect_timed_out!(host, port, elapsed_seconds, cause = nil)
+      detail = cause ? " Driver reported: #{cause.message.to_s.gsub(/\s+/, " ").strip}" : ""
+      raise Tina4::DatabaseConnectionError,
+            "Database connect to #{host}:#{port} timed out after " \
+            "#{format("%.1f", elapsed_seconds)}s (#{CONNECT_TIMEOUT_VAR}=" \
+            "#{connect_timeout_seconds} seconds; set it to 0 to wait " \
+            "indefinitely).#{detail}"
+    end
+
+    # Run a driver's natively-bounded connect and translate an expiry into the
+    # contract error above. The NATIVE option does the bounding; this only names
+    # it. Whether the bound expired is decided by ELAPSED TIME, not by matching
+    # driver error text - the four clients word it four different ways
+    # ("timeout expired", "waiting for initial communication packet", "TDS
+    # server connection timed out", "Connection timed out"), and a marker table
+    # is one more thing to drift and MISS. A missed timeout is the whole defect.
+    def self.bounding_connect(host, port)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    rescue StandardError => error
+      bound = connect_timeout_seconds
+      raise if bound.nil?
+
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+      raise if elapsed < bound - CONNECT_TIMEOUT_SLACK_SECONDS
+
+      connect_timed_out!(host, port, elapsed, error)
+    end
+
+    # Did this driver actually OVERRIDE the contract method, or is it inheriting
+    # the raising stub? `respond_to?` cannot answer that once the module is
+    # included, and answering it wrongly turns a working silent-skip path into a
+    # NotImplementedError at runtime.
+    def self.implemented_by?(object, name)
+      return false unless object.respond_to?(name)
+
+      owner = begin
+        object.class.instance_method(name).owner
+      rescue NameError
+        nil
+      end
+      !owner.nil? && owner != self
+    end
+  end
+end