tina4ruby 3.13.93 → 3.13.96

data/lib/tina4/database.rb

@@ -5,6 +5,15 @@ require "digest"
 require "weakref"
 
 module Tina4
+  # Raised at the first USE of a database whose connect failed.
+  #
+  # Connecting is deliberately non-fatal at boot (log loud, then degrade - the same
+  # policy the session backends follow), so the failure has to resurface somewhere.
+  # It used to resurface as a nil dereference inside the driver
+  # ("NoMethodError: private method `exec' called for nil:NilClass"), which named
+  # neither the database nor the reason. This carries both.
+  class DatabaseConnectionError < StandardError; end
+
   # Thread-safe connection pool with round-robin rotation.
   # Connections are created lazily on first use.
   class ConnectionPool
@@ -136,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,
@@ -191,6 +305,9 @@ module Tina4
                      pool
                    end
       @connected = false
+      # Set by #connect when connecting fails; re-raised with context by
+      # #current_driver so the first real call says what went wrong.
+      @connect_error = nil
 
       # Per-instance thread-local key for the transaction adapter pin.
       # Without this pin, every Database method call rotates to a different
@@ -298,12 +415,24 @@ 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
     rescue => e
       Tina4::Log.error("Database connection failed: #{e.message}")
       @connected = false
+      # REMEMBER the cause. Logging alone is not enough: the driver's own
+      # connection stays nil, so the next call used to die inside the driver as
+      #   NoMethodError: private method `exec' called for nil:NilClass
+      # which names neither the database it failed to reach nor why. That cost
+      # real debugging time when a missing test database looked like a driver
+      # bug. current_driver re-raises this with context instead.
+      #
+      # Boot still does NOT crash on an unreachable database (deliberate, and
+      # the same log-loud-then-degrade policy the session backends use) - the
+      # error surfaces at the first actual USE.
+      @connect_error = e
     end
 
     def close
@@ -324,6 +453,11 @@ module Tina4
     def current_driver
       pinned = Thread.current[@tx_pin_key]
       return pinned if pinned
+
+      # Fail with the REAL reason, at the point of use. Without this the caller
+      # gets a nil dereference from deep inside the driver and has to guess.
+      raise Tina4::DatabaseConnectionError, connect_error_message if @connect_error
+
       if @pool
         @pool.checkout
       else
@@ -331,6 +465,30 @@ module Tina4
       end
     end
 
+    # A message that says which database, on which driver, and why - the three
+    # things the old nil-dereference told you nothing about.
+    def connect_error_message
+      target = safe_connection_target
+      "Database not connected (#{@driver_name}#{target.empty? ? '' : " -> #{target}"}): " \
+        "#{@connect_error.class}: #{@connect_error.message}"
+    end
+
+    # 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
+      Tina4::DatabaseUrl.redact(@connection_string)
+    end
+
     # ── Query Cache ──────────────────────────────────────────────
 
     def cache_stats
@@ -425,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
@@ -441,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).
@@ -514,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
@@ -538,61 +729,150 @@ 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
 
+    # The table's primary-key columns, introspected once and cached.
+    #
+    # Returns an ARRAY because a primary key may span several columns. A
+    # composite key is still one primary key; it just has more than one column.
+    # Returns [] when the table has no primary key or cannot be introspected.
+    #
+    # Uses the cross-engine columns() contract (v3.13.14, #48), which reports
+    # :primary_key per column on every driver.
+    def primary_key(table)
+      @pk_cache ||= {}
+      unless @pk_cache.key?(table)
+        @pk_cache[table] = begin
+          columns(table).select { |c| c[:primary_key] }.map { |c| c[:name].to_s }
+        rescue StandardError
+          []
+        end
+      end
+      @pk_cache[table]
+    end
+
+    # Normalise a filter to [sql, params], accepting a Hash or a String.
+    def as_where(filter, params)
+      return ["", []] if filter.nil?
+
+      if filter.is_a?(Hash)
+        return ["", []] if filter.empty?
+
+        drv = current_driver
+        [filter.keys.map { |k| "#{k} = #{drv.placeholder}" }.join(" AND "), filter.values]
+      else
+        [filter.to_s, Array(params)]
+      end
+    end
+    private :as_where
+
+    # Update rows. A write with no filter is an error, not a full-table write.
+    #
+    # With no explicit filter the primary key is taken out of `data` and used as
+    # the WHERE clause. With neither a filter nor a primary key in `data` this
+    # raises rather than overwriting every row (audit feature 4, P1).
     def update(table, data, filter = {}, params = nil)
-      cache_invalidate if @cache_enabled
-      drv = current_driver
+      where_sql, where_params = as_where(filter, params)
+      data = data.dup
+
+      if where_sql.empty?
+        pk_columns = primary_key(table)
+        # 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|
+          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)
+
+        if pk_columns.empty? || !missing.empty?
+          raise ArgumentError,
+                "update requires a filter or the complete primary key in the data; " \
+                "pass a filter explicitly to update multiple rows " \
+                "(table=#{table.inspect}, primary key=#{pk_columns.inspect}, " \
+                "missing from data=#{missing.inspect}). " \
+                "To empty a table use truncate(#{table.inspect})."
+        end
 
-      # String filter with explicit params array
-      if filter.is_a?(String) && !params.nil?
-        set_parts = data.keys.map { |k| "#{k} = #{drv.placeholder}" }
-        sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
-        sql += " WHERE #{filter}" unless filter.empty?
-        drv.execute(sql, data.values + Array(params))
-        autocommit_standalone_write(drv)
-        return Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+        # EVERY key column goes into the WHERE. A composite key built from only
+        # its first column would match every row sharing that value - the
+        # data-loss bug this method exists to prevent, reintroduced.
+        where_params = pk_keys.map { |k| data.delete(k) }
+        if data.empty?
+          raise ArgumentError,
+                "update was given only the primary key #{pk_columns.inspect} and no " \
+                "columns to set (table=#{table.inspect})"
+        end
+
+        where_sql = pk_columns.map { |c| "#{c} = #{current_driver.placeholder}" }.join(" AND ")
       end
 
+      cache_invalidate if @cache_enabled
+      drv = current_driver
       set_parts = data.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      where_parts = filter.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
-      sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
-      values = data.values + filter.values
-      drv.execute(sql, values)
+      sql = "UPDATE #{table} SET #{set_parts.join(', ')} WHERE #{where_sql}"
+      drv.execute(sql, data.values + where_params)
       autocommit_standalone_write(drv)
-      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
     end
 
+    # Delete rows. A filterless delete raises; use truncate() to empty a table.
     def delete(table, filter = {}, params = nil)
-      cache_invalidate if @cache_enabled
-      drv = current_driver
-
       # List of hashes — delete each row
       if filter.is_a?(Array)
         total = 0
         filter.each { |row| total += delete(table, row).affected_rows }
-        return Tina4::DatabaseResult.new([], affected_rows: total)
+        return Tina4::DatabaseResult.new([], affected_rows: total, last_id: nil)
       end
 
-      # String filter — raw WHERE clause with optional params
-      if filter.is_a?(String)
-        sql = "DELETE FROM #{table}"
-        sql += " WHERE #{filter}" unless filter.empty?
-        drv.execute(sql, Array(params))
-        autocommit_standalone_write(drv)
-        return Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      where_sql, where_params = as_where(filter, params)
+      if where_sql.empty?
+        raise ArgumentError,
+              "delete requires a filter (table=#{table.inspect}). " \
+              "To remove every row use truncate(#{table.inspect})."
       end
 
-      # Hash filter — build WHERE from keys
-      where_parts = filter.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      sql = "DELETE FROM #{table}"
-      sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
-      drv.execute(sql, filter.values)
+      cache_invalidate if @cache_enabled
+      drv = current_driver
+      drv.execute("DELETE FROM #{table} WHERE #{where_sql}", where_params)
+      autocommit_standalone_write(drv)
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
+    end
+
+    # Remove every row. The explicit spelling of a whole-table delete.
+    def truncate(table)
+      cache_invalidate if @cache_enabled
+      drv = current_driver
+      drv.execute("DELETE FROM #{table} WHERE 1 = 1", [])
       autocommit_standalone_write(drv)
-      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
     end
 
     # Return the last execute() error message, or nil.
@@ -685,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
@@ -702,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,
@@ -820,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
@@ -938,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
@@ -965,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
@@ -1057,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
@@ -1239,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)
@@ -1330,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:/