rails-ai-context 5.35.0 → 5.35.2

data/lib/rails_ai_context/database_family/sqlite_runtime.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "set"
+
+module RailsAiContext
+  module DatabaseFamily
+    # sqlite3-ruby holds the interpreter lock while a statement steps, so only a killable child ends
+    # one at the deadline. A statement the child cannot run goes to the app's own connection, unbounded.
+    module SqliteRuntime
+      module_function
+
+      TIMED_OUT = "SQLite query exceeded the statement timeout"
+
+      # A row-capped result is far below this; a larger prefix is a corrupt one.
+      MAX_RESULT_BYTES = 1 << 30
+
+      # What the child writes where a result's length would stand, the moment it meets a lock.
+      MET_LOCK = [ (1 << 64) - 1 ].pack("Q>").freeze
+      # What it writes once it holds its read lock: no lock can stop the statement from there on.
+      PAST_LOCK = [ (1 << 64) - 2 ].pack("Q>").freeze
+      WAITS_ON_LOCK = { MET_LOCK => true, PAST_LOCK => false }.freeze
+
+      # A plan row that reads a table: the step, then the table's name or, for a table the statement
+      # renames, the alias alone ("SEARCH u USING INDEX i"). SQLite before 3.36 wrote "SCAN TABLE users AS u".
+      PLAN_STEP = /\A(SCAN|SEARCH)\s+(?:TABLE\s+)?(.+?)(?:\s+AS\s+\S+)?(?=\s+USING\b|\s+VIRTUAL TABLE\b|\z)/
+
+      # pragma_table_xinfo's hidden flag: 2 is a virtual generated column, 3 a stored one.
+      GENERATED = [ 2, 3 ].freeze
+
+      # COUNT(*) walks the whole table; a count that stops here reads at most this many rows.
+      COUNT_CAP = 100_000
+
+      def read_only(conn, sql, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        # A child opens the file itself and would answer without the rows of a transaction open here.
+        if !conn.transaction_open? && (path = fork_path(conn)) && !DatabaseFamily.bounding { held_here?(conn, sql) }
+          result = in_child(conn, path, sql, deadline)
+          return Rows.new(result.columns, result.rows, false) if result
+        end
+
+        result = DatabaseFamily.bounding { on_app_connection(conn, sql, deadline) }
+        Rows.new(result.columns, result.rows, true)
+      end
+
+      # The temp catalog, the temp schema, and a pragma function or dbstat: each reads any schema, by a name that can be put
+      # together as the statement runs.
+      CONNECTION_CATALOG = /(?<![\w$])(?:sqlite_temp_(?:master|schema)|temp["`'\]]?\s*\.|pragma_\w|dbstat(?![\w$]))/i
+
+      # Whether the statement names what the connection holds and a child would answer wrongly: a temp object, the temp schema or
+      # an attached database, in a string too. A table only an attached database holds needs no match: no child can prepare it.
+      def held_here?(conn, sql)
+        # Neither read waits on another connection's lock, which the pragma function for the same list does.
+        names = conn.select_rows("PRAGMA database_list").filter_map { |_seq, name, _file| name unless OWN_SCHEMAS.include?(name) } +
+          conn.select_values("SELECT name FROM sqlite_temp_master")
+        return false if names.empty?
+
+        sql.match?(CONNECTION_CATALOG) || SecretColumns.fold(sql).match?(Regexp.union(names.map { |name| SecretColumns.identifier(name) }))
+      end
+
+      # The watchdog's interrupt lands when the driver is back in Ruby between two rows, so it ends a
+      # statement that returns rows slowly and cannot end one long step: the run counts as unbounded.
+      def on_app_connection(conn, sql, deadline)
+        left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise TimedOut, TIMED_OUT unless left.positive?
+
+        raw = conn.raw_connection
+        found = conn.select_value("PRAGMA query_only").to_i
+        watchdog = Thread.new { sleep(left) and raw.interrupt }
+        begin
+          conn.execute("PRAGMA query_only = ON")
+          conn.select_all(sql)
+        rescue ActiveRecord::StatementInvalid => e
+          raise TimedOut, TIMED_OUT if e.cause.is_a?(SQLite3::InterruptException)
+
+          raise
+        ensure
+          watchdog.kill.join
+          DatabaseFamily.restore(conn, "PRAGMA query_only = #{found}")
+        end
+      end
+
+      # These reads run on the app's own connection, where a wait on another writer ends at the
+      # connection's busy timeout (database.yml `timeout`; with none, a busy database fails at once).
+      def bounded(_conn, _timeout, &reads)
+        DatabaseFamily.bounding(&reads)
+      end
+
+      def explain(conn, sql, timeout)
+        result = read_only(conn, "EXPLAIN QUERY PLAN #{sql}", timeout)
+        scans = []
+        warnings = []
+        tables = conn.data_sources.map(&:downcase)
+        raw_lines = result.rows.map do |row|
+          # Columns: id, parent, notused, detail.
+          detail = row.last.to_s
+          step, name = detail.match(PLAN_STEP)&.captures
+          # "SCAN CONSTANT ROW" reads no table.
+          if step && name != "CONSTANT ROW"
+            table = tables.include?(name.downcase) ? name : "#{name} (a name the statement gives)"
+            type = if step == "SEARCH" then "index search"
+            elsif detail.match?(/USING.*INDEX/) then "index scan"
+            else "full table scan"
+            end
+            scans << { table: table, type: type, index: detail[/USING.*INDEX\s+(\w+)/, 1] }
+            warnings << "Full table scan on #{table}" if type == "full table scan"
+          end
+          detail
+        end
+        { scan_types: scans, warnings: warnings, raw: raw_lines.join("\n"), unbounded: result.unbounded }
+      end
+
+      def column_sources(_conn, _sql, _plan)
+        []
+      end
+
+      def plan(_conn, _sql, _timeout)
+        nil
+      end
+
+      # The attached databases. A statement reaches their tables with no schema named, as it does main's and temp's.
+      def unqualified_schemas(conn)
+        conn.select_rows("PRAGMA database_list").map { |_seq, name, _file| name } | OWN_SCHEMAS
+      end
+
+      def schemas_named(_conn, _names)
+        []
+      end
+
+      OWN_SCHEMAS = %w[main temp].freeze
+
+      # One SELECT for each schema, as one statement. Yields the schema as an identifier and as a string,
+      # which is how a pragma function takes it.
+      def across(schemas)
+        (schemas.empty? ? OWN_SCHEMAS : schemas).map { |schema| yield %("#{schema.gsub('"', '""')}"), "'#{schema.gsub("'", "''")}'" }.join(" UNION ALL ")
+      end
+
+      # A virtual table's hidden columns are left out (hidden = 1): a full-text table has one of its own name.
+      def relation_columns(conn, schemas = [])
+        DatabaseFamily.by_table(conn.select_rows(across(schemas) do |schema, name|
+          "SELECT m.name, p.name FROM #{schema}.sqlite_master m JOIN pragma_table_xinfo(m.name, #{name}) p " \
+            "WHERE m.type = 'table' AND m.name NOT LIKE 'sqlite_%' AND p.hidden <> 1"
+        end)).transform_values(&:flatten)
+      end
+
+      # The body only: the header names the view itself.
+      def view_definitions(conn, schemas = [])
+        rows = conn.select_rows(across(schemas) { |schema, _| "SELECT name, sql FROM #{schema}.sqlite_master WHERE type = 'view'" })
+        DatabaseFamily.by_view(rows.map { |name, sql| [ name, sql.to_s.sub(/\A.*?\bAS\b/mi, "") ] })
+      end
+
+      def traced_views(_conn, _schemas = [])
+        []
+      end
+
+      # SQLite keeps no expression per column, so each one is cut from its table's definition. A column whose
+      # part of the definition is not found answers the whole definition.
+      def generated_columns(conn, schemas = [])
+        rows = conn.select_rows(across(schemas) do |schema, name|
+          "SELECT m.name, p.name, p.hidden, m.sql FROM #{schema}.sqlite_master m JOIN pragma_table_xinfo(m.name, #{name}) p " \
+            "WHERE m.type = 'table' AND m.name NOT LIKE 'sqlite_%' AND m.sql LIKE '%AS%(%'"
+        end)
+        # Tables of one name in two schemas each have a definition of their own.
+        rows.group_by { |table, _name, _hidden, definition| [ table, definition.to_s ] }.each_with_object({}) do |((table, definition), columns), found|
+          generated = columns.filter_map { |_table, name, hidden, _| name if GENERATED.include?(hidden.to_i) }
+          next if generated.empty?
+
+          expressions = column_expressions(definition)
+          DatabaseFamily.keep_expressions(found, generated.map { |name| [ table, name, expressions[name.downcase(:ascii)] || definition ] })
+        end
+      end
+
+      COLUMN_NAME = /\A(?:"((?:""|[^"])*)"|`((?:``|[^`])*)`|\[([^\]]*)\]|'((?:''|[^'])*)'|([^\s(]+))(.*)\z/m
+      # A bare one of these opens a table constraint. In quotes it is a column's name.
+      TABLE_CONSTRAINT = /\A(?:CONSTRAINT|PRIMARY|UNIQUE|CHECK|FOREIGN)\z/i
+
+      # @return [Hash{String => String, nil}] column name, folded as SQLite compares names (ASCII only) => what its
+      #   part of a CREATE TABLE statement says after AS; nil where that cannot be told
+      def column_expressions(definition)
+        scanner = SqlGate::Scanner.new(SqlGate.comment_free(definition, SQLITE))
+        depth = 0
+        parts = [ +"" ]
+        until scanner.eos?
+          read = SqlGate.quoted(scanner, SQLITE)&.last || scanner.getch
+          depth -= 1 if read == ")"
+          if depth == 1 && read == "," then parts << +""
+          elsif depth.positive? then parts.last << read
+          end
+          depth += 1 if read == "("
+        end
+        parts.each_with_object({}) do |part, found|
+          double, tick, bracket, single, bare, rest = part.strip.match(COLUMN_NAME)&.captures
+          next if rest.nil? || bare&.match?(TABLE_CONSTRAINT)
+
+          # A quote is doubled only inside a name its own kind encloses, and a bracketed name doubles nothing.
+          name = (bare || bracket || double&.gsub('""', '"') || tick&.gsub("``", "`") || single.gsub("''", "'")).downcase(:ascii)
+          found[name] = found.key?(name) ? nil : rest.partition(/\bAS\b/i).last.presence
+        end
+      end
+
+      # pragma_table_list, which types a shadow table, came with this version.
+      TYPED_TABLES = "3.37"
+      VOCABULARY = /\A\s*USING\s+["'`\[]?(fts5vocab|fts4aux)\b["'`\]]?\s*\((.*)\)/mi
+
+      # Modules that return the database file's pages or cells, whatever table they belong to.
+      PAGE_MODULES = %w[sqlite_dbpage sqlite_dbdata sqlite_dbptr].freeze
+
+      # Before pragma_table_list a shadow table is told by its name: any table that starts with a virtual table's.
+      def index_tables(conn, schemas = [])
+        tables = ->(kept) { across(schemas) { |schema, _| "SELECT name, sql FROM #{schema}.sqlite_master WHERE type = 'table' AND rootpage #{kept}" } }
+        virtual = conn.select_rows(tables.call("= 0")).to_h
+        stored = if conn.database_version >= TYPED_TABLES
+          conn.select_values(across(schemas) { |_, name| "SELECT name FROM pragma_table_list WHERE type = 'shadow' AND schema = #{name} COLLATE NOCASE" })
+        else conn.select_rows(tables.call("> 0")).map(&:first)
+        end
+        found = stored.each_with_object(PAGE_MODULES.to_h { |name| [ name, [ :pages, nil ] ] }) do |name, tables|
+          owner = virtual.keys.select { |table| name.downcase.start_with?("#{table.downcase}_") }.max_by(&:size)
+          tables[name] = [ :shadow, owner ] if owner
+        end
+        virtual.each do |name, sql|
+          clause = module_clause(SqlGate.comment_free(sql.to_s, SQLITE))
+          mod, args = clause.match(VOCABULARY)&.captures
+          # fts5vocab([schema,] table, type) and fts4aux([schema,] table).
+          names = args.to_s.scan(SecretColumns::MODULE_ARGUMENT).map { |arg| arg.strip.delete(%q('"`[])) }
+          found[name] = mod ? [ :vocabulary, mod.casecmp?("fts4aux") ? names.last : names[-2], clause ] : [ :virtual, name, clause ]
+        end
+        found
+      end
+
+      # What a virtual table's definition says after the table's own name: `USING module(arguments)`.
+      # SQLite stores it from the name on, and a quoted name can hold the word USING.
+      def module_clause(sql)
+        scanner = SqlGate::Scanner.new(sql)
+        scanner.skip(/\s*CREATE\s+VIRTUAL\s+TABLE\s+/i)
+        SqlGate.quoted(scanner, SQLITE) || scanner.skip(/[^\s"'`\[]+/)
+        scanner.rest
+      end
+
+      def table_sizes(conn)
+        # dbstat lists every b-tree, indexes and SQLite internals too.
+        app_tables = conn.select_values("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").to_set
+
+        begin
+          rows = conn.select_all("SELECT name, SUM(pgsize) AS bytes FROM dbstat GROUP BY name ORDER BY bytes DESC")
+            .filter_map { |r| { name: r["name"], bytes: r["bytes"].to_i } if app_tables.include?(r["name"]) }
+          return rows if rows.any?
+        rescue => e
+          RailsAiContext.debug_fail(e, label: "SqliteRuntime.table_sizes (dbstat)")
+        end
+
+        # Without dbstat, the whole file split across the tables.
+        total = conn.select_value("PRAGMA page_count").to_i * conn.select_value("PRAGMA page_size").to_i
+        tables = app_tables.to_a.sort
+        tables.map { |t| { name: t, bytes: total / [ tables.size, 1 ].max } }
+      end
+
+      # SQLite keeps no row estimate a query can read without ANALYZE; a table past the cap is a floor.
+      def row_estimates(conn)
+        names = (conn.tables - Introspectors::SqliteVirtualTables.hidden(conn)).reject { |t| t.start_with?("ar_internal_metadata", "schema_migrations") }
+        names.map do |table|
+          count = conn.select_value("SELECT COUNT(*) FROM (SELECT 1 FROM #{conn.quote_table_name(table)} LIMIT #{COUNT_CAP + 1})").to_i
+          entry = { table: table, approximate_rows: [ count, COUNT_CAP ].min }
+          entry[:at_least] = true if count > COUNT_CAP
+          entry
+        end.sort_by { |t| [ -t[:approximate_rows], t[:table] ] }
+      end
+
+      def index_usage(_conn)
+        nil
+      end
+
+      # nil for an in-memory or temporary database, or where there is no fork.
+      def fork_path(conn)
+        return nil unless Process.respond_to?(:fork)
+
+        path = conn.raw_connection.filename("main").to_s
+        path unless path.empty?
+      end
+
+      # @return [ActiveRecord::Result, nil] nil when the child could not prepare the statement, as when it
+      #   names a function, module, collation, key or temporary table only the app's connection has
+      def in_child(conn, path, sql, deadline)
+        parent = Process.pid
+        extensions = Array(conn.pool.db_config.configuration_hash[:extensions]).map { |ext| (ext.is_a?(String) && ext.safe_constantize) || ext }
+        # sqlite3 2.x warns in every child that inherits a writable handle; Rails 8 silences it the same way.
+        SQLite3::ForkSafety.suppress_warnings! if defined?(SQLite3::ForkSafety)
+
+        timeout = [ deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0 ].max
+        reader, writer = IO.pipe.each(&:binmode)
+        pid = fork { answer_in_child(reader, writer, path, sql, timeout, extensions) }
+        writer.close
+        read_child_result(reader, deadline)
+      ensure
+        # Also reached in a child whose fork hooks raised: it must not carry on as a second server.
+        exit!(1) if parent && Process.pid != parent
+        reader&.close
+        writer&.close
+        reap_child(pid) if pid
+      end
+
+      # Writes the length-prefixed result and exits without the parent's at_exit hooks.
+      def answer_in_child(reader, writer, path, sql, timeout, extensions)
+        reader.close
+        payload = begin
+          db = SQLite3::Database.new(path, readonly: true, extensions: extensions)
+          wait_on_lock(db, writer, timeout * 0.8)
+          # A read inside a transaction keeps its lock, so the statement itself never waits on one.
+          db.execute("BEGIN")
+          db.execute("SELECT 1 FROM sqlite_master LIMIT 1")
+          writer.write(PAST_LOCK)
+          stmt = db.prepare(sql)
+          [ :ok, stmt.columns, stmt.to_a ]
+        rescue => e
+          # Which step failed is the child's own fact; the message can hold text from the statement.
+          status = if e.is_a?(SQLite3::BusyException) then :busy
+          else db && !stmt ? :unprepared : :error
+          end
+          [ status, "#{e.class}: #{e.message}" ]
+        end
+        bytes = Marshal.dump(payload)
+        writer.write([ bytes.bytesize ].pack("Q>"), bytes)
+      ensure
+        exit!(0)
+      end
+
+      # Gives up under the deadline, so the child answers a database that stays locked. The parent is told at
+      # the first wait, for a child that started late and is still waiting at the deadline.
+      def wait_on_lock(db, writer, seconds)
+        met = nil
+        db.busy_handler do |count|
+          if count.zero?
+            met = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            writer.write(MET_LOCK)
+          end
+          sleep 0.01
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) - met < seconds
+        end
+      end
+
+      # Read by length: any other process forked meanwhile holds a copy of the writer, so EOF may never come.
+      # A deadline that passes while the child waits on a lock is answered as locked; past the lock it is the timeout.
+      def read_child_result(reader, deadline)
+        on_lock = false
+        size = begin
+          loop do
+            prefix = read_before(reader, 8, deadline)
+            break prefix.unpack1("Q>") unless WAITS_ON_LOCK.key?(prefix)
+
+            on_lock = WAITS_ON_LOCK.fetch(prefix)
+          end
+        rescue TimedOut
+          raise unless on_lock
+
+          raise Busy, BUSY
+        end
+        status, *rest = begin
+          raise ArgumentError, "result length out of range" if size > MAX_RESULT_BYTES
+
+          Marshal.load(read_before(reader, size, deadline))
+        rescue ArgumentError, TypeError
+          raise ActiveRecord::StatementInvalid, "the SQLite query process exited without a result"
+        end
+        raise Busy, BUSY if status == :busy
+        raise ActiveRecord::StatementInvalid, rest.first if status == :error
+        return nil if status == :unprepared
+
+        ActiveRecord::Result.new(*rest)
+      end
+
+      def read_before(reader, size, deadline)
+        data = "".b
+        while data.bytesize < size
+          left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise TimedOut, TIMED_OUT unless left.positive? && IO.select([ reader ], nil, nil, left)
+
+          chunk = reader.read_nonblock([ size - data.bytesize, 1 << 16 ].min, exception: false)
+          raise ActiveRecord::StatementInvalid, "the SQLite query process exited without a result" if chunk.nil?
+
+          data << chunk unless chunk == :wait_readable
+        end
+        data
+      end
+
+      # KILL: TERM cannot land while `step` holds the GVL, and would run inherited at_exit hooks.
+      # Runs in an ensure, so it rescues everything: nothing here may replace the query's own error.
+      def reap_child(pid)
+        Process.kill(:KILL, pid) rescue nil
+        Process.wait(pid) rescue nil
+      end
+    end
+  end
+end

data/lib/rails_ai_context/database_family.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # What a database is by its adapter's name: PostgreSQL, MySQL or SQLite, else no family (ADR-0008).
+  # A family also owns how its database runs a guarded read and the statistics other tools show.
+  module DatabaseFamily
+    # A statement ran past the timeout it was given.
+    class TimedOut < RailsAiContext::Error; end
+
+    # Another connection holds a lock on the database, so the statement did not run.
+    class Busy < RailsAiContext::Error; end
+
+    # The read cannot be guarded (an adapter with no family, a MySQL transaction already open), so nothing was sent.
+    class Unsupported < RailsAiContext::Error; end
+
+    # Rows from a guarded read; unbounded when no timeout could hold it.
+    Rows = Data.define(:columns, :rows, :unbounded)
+
+    Family = Data.define(:key, :name) do
+      def known?
+        key != :unknown
+      end
+
+      def postgresql?
+        key == :postgresql
+      end
+
+      def mysql?
+        key == :mysql
+      end
+
+      def sqlite?
+        key == :sqlite
+      end
+
+      def implicit_pk_type
+        sqlite? ? "integer" : "bigint"
+      end
+
+      # A statement is checked against its plan before it runs, and a result column is traced to its table column.
+      def plan_checks?
+        postgresql?
+      end
+
+      # The read-only transaction refuses FOR UPDATE and FOR SHARE itself.
+      def refuses_locking_reads?
+        postgresql?
+      end
+
+      # Every string literal in a statement can be told from its identifiers.
+      def masks_literals?
+        postgresql?
+      end
+
+      def dollar_quoting?
+        postgresql?
+      end
+
+      # A block comment inside a block comment needs a closer of its own.
+      def nested_comments?
+        postgresql?
+      end
+
+      # `/*! ... */` holds text the database runs.
+      def executable_comments?
+        mysql?
+      end
+
+      # A backslash escapes the next character in every string.
+      def backslash_escapes?
+        mysql?
+      end
+
+      # @return [Regexp] a comment that runs to the end of its line: `#` too, and `--` only before a space, on MySQL
+      def line_comment
+        mysql? ? /--(?=\s|\z)[^\n]*|#[^\n]*/ : /--[^\n]*/
+      end
+
+      # @return [Rows] run in a read-only transaction, bounded by timeout seconds
+      # @raise [TimedOut, Unsupported]
+      def read_only(connection, sql, timeout:)
+        runtime.read_only(connection, sql, timeout)
+      end
+
+      # Runs reads beside the statement so that each one ends at timeout seconds, a wait on a lock included.
+      # @raise [TimedOut, Unsupported]
+      def bounded(connection, timeout:, &reads)
+        runtime.bounded(connection, timeout, &reads)
+      end
+
+      # @return [Hash] { scan_types:, warnings:, raw:, unbounded: }
+      def explain(connection, sql, timeout:)
+        runtime.explain(connection, sql, timeout)
+      end
+
+      # @raise [TimedOut, ActiveRecord::StatementInvalid] when PostgreSQL cannot plan the statement
+      # @return [Hash, nil] the PostgreSQL JSON plan's top node; nil on other families or when the answer is no plan
+      def plan(connection, sql, timeout:)
+        runtime.plan(connection, sql, timeout)
+      end
+
+      # @return [Array<Array(Integer, String, String)>] [result column index, table column, relation] from the
+      #   plan; the column is nil where the relation's columns could not be read; [] where the family cannot say
+      def column_sources(connection, sql, plan:)
+        runtime.column_sources(connection, sql, plan)
+      end
+
+      # A schema read that is given no schemas reads at least what a statement reaches with no schema named:
+      # the PostgreSQL search path, the MySQL connection's database, SQLite's main and temp.
+
+      # @return [Array<String>] the schemas a statement reaches with no schema named, where the reads' own
+      #   default does not cover them: SQLite's attached databases
+      def unqualified_schemas(connection)
+        runtime.unqualified_schemas(connection)
+      end
+
+      # @return [Array<String>] the names among these that are schemas a statement can read and the reads' own
+      #   default does not cover. System schemas are left out.
+      def schemas_named(connection, names)
+        names.empty? ? [] : runtime.schemas_named(connection, names)
+      end
+
+      # @return [Hash{String => Array<String>}] relation name => its column names, from one catalogue read. On
+      #   PostgreSQL also under `schema.relation`, where the bare name holds the columns of every schema read.
+      def relation_columns(connection, schemas = [])
+        runtime.relation_columns(connection, schemas)
+      end
+
+      # @return [Hash{String => String, nil}] view name => the definition the database stores, nil for one it
+      #   will not show. On PostgreSQL also under `schema.view`, as traced_views names it too.
+      def view_definitions(connection, schemas = [])
+        runtime.view_definitions(connection, schemas)
+      end
+
+      # @return [Array<String>] the views whose result columns column_sources traces to their table columns
+      def traced_views(connection, schemas = [])
+        runtime.traced_views(connection, schemas)
+      end
+
+      # @return [Hash{String => Hash{String => String}}] table name => { generated column => its expression }
+      def generated_columns(connection, schemas = [])
+        runtime.generated_columns(connection, schemas)
+      end
+
+      # @return [Hash{String => Array}] what holds another table's rows or words under other names: table =>
+      #   [:pages, :shadow, :vocabulary or :virtual, its virtual table, and for the last two kinds their definition]
+      def index_tables(connection, schemas = [])
+        runtime.index_tables(connection, schemas)
+      end
+
+      # @return [Array<Hash>, nil] { name:, bytes: } largest first; nil when the family has none
+      def table_sizes(connection)
+        runtime.table_sizes(connection)
+      end
+
+      # @return [Array<Hash>, nil] { table:, approximate_rows: } most rows first
+      def row_estimates(connection)
+        runtime.row_estimates(connection)
+      end
+
+      # @return [Array<Hash>, nil] { table:, index:, scans: } least used first
+      def index_usage(connection)
+        runtime.index_usage(connection)
+      end
+
+      private
+
+      def runtime
+        case key
+        when :postgresql then PostgresqlRuntime
+        when :mysql then MysqlRuntime
+        when :sqlite then SqliteRuntime
+        else
+          raise Unsupported, "The #{name} adapter has no database family, so its read-only transaction " \
+            "and statement timeout are not known. Supported: PostgreSQL, MySQL (with MariaDB) and SQLite."
+        end
+      end
+    end
+
+    POSTGRESQL = Family.new(:postgresql, "PostgreSQL")
+    MYSQL = Family.new(:mysql, "MySQL")
+    SQLITE = Family.new(:sqlite, "SQLite")
+
+    # Live adapter_name values, database.yml adapters, URL schemes, display labels and dump dialects, downcased.
+    NAMES = {
+      "postgresql" => POSTGRESQL, "postgis" => POSTGRESQL, "postgres" => POSTGRESQL,
+      "mysql2" => MYSQL, "trilogy" => MYSQL, "mysql" => MYSQL, "mariadb" => MYSQL,
+      "sqlite3" => SQLITE, "sqlite" => SQLITE
+    }.freeze
+
+    DEFAULT_SUFFIX = " by database.yml default"
+
+    # 3024 MySQL max_execution_time, 1317 query interrupted, 1969 MariaDB max_statement_time, 1205 lock_wait_timeout.
+    TIMEOUT_CODES = [ 3024, 1317, 1969, 1205 ].freeze
+
+    module_function
+
+    # @param source [#adapter_name, #adapter, String, Symbol, nil]
+    # @return [Family] never raises; no family carries the raw name
+    def of(source)
+      raw = raw_name(source)
+      NAMES.fetch(raw.downcase.delete_suffix(DEFAULT_SUFFIX)) { Family.new(:unknown, raw.empty? ? "unknown" : raw) }
+    end
+
+    def raw_name(source)
+      source = source.adapter_name if source.respond_to?(:adapter_name)
+      source = source.adapter if source.respond_to?(:adapter)
+      source.is_a?(String) || source.is_a?(Symbol) ? source.to_s : ""
+    rescue StandardError
+      ""
+    end
+
+    # @return [Hash{String => Array<Array>}] catalogue rows grouped by their first field, the table, without it
+    def by_table(rows)
+      rows.group_by(&:first).transform_values { |found| found.map { |row| row.drop(1) } }
+    end
+
+    # @return [Hash{String => String, nil}] [view, definition] rows by view. Views of one name in two schemas
+    #   are read as one text, and as unreadable when either is.
+    def by_view(rows)
+      rows.group_by(&:first).transform_values { |found| found.map(&:last).then { |texts| texts.all? ? texts.join("\n") : nil } }
+    end
+
+    # Adds [table, generated column, expression] rows to found, as table => { column => expression }. Tables of one
+    # name in two schemas keep every expression their columns of one name have.
+    def keep_expressions(found, rows)
+      rows.each_with_object(found) do |(table, column, expression), kept|
+        (kept[table] ||= {}).merge!(column => expression.to_s) { |_column, known, read| known.include?(read) ? known : "#{known} #{read}" }
+      end
+    end
+
+    BUSY = "The database is locked by another connection, so the query did not run. Run it again when the other connection has finished."
+
+    # Runs the block and raises TimedOut for a database's timeout, Busy for a locked SQLite database. Message text is never read.
+    def bounding
+      yield
+    rescue ActiveRecord::StatementInvalid => e
+      raise Busy, BUSY if busy?(e)
+      raise TimedOut, e.message if timed_out?(e)
+
+      raise
+    end
+
+    # Puts a session setting back. A failed restore never replaces the caller's own error, and the
+    # connection it left changed leaves the pool so no later statement inherits the setting.
+    def restore(connection, statement)
+      connection.execute(statement)
+    rescue StandardError
+      begin
+        connection.respond_to?(:throw_away!) ? connection.throw_away! : connection.disconnect!
+      rescue StandardError
+        nil
+      end
+    end
+
+    # A connection the server dropped: the caller's to answer, and no reason to fall back to another read.
+    def lost_connection?(error)
+      error.is_a?(ActiveRecord::ConnectionNotEstablished) ||
+        (defined?(ActiveRecord::ConnectionFailed) && error.is_a?(ActiveRecord::ConnectionFailed))
+    end
+
+    # A SQLite read that found the database locked, at once or after the connection's busy timeout.
+    # Rails 7.0 gives it no class of its own.
+    def busy?(error)
+      defined?(SQLite3::BusyException) && error.cause.is_a?(SQLite3::BusyException)
+    end
+
+    def timed_out?(error)
+      # A connection the server dropped is a QueryAborted on Rails 7.1 and later, and it is no timeout.
+      return false if defined?(ActiveRecord::ConnectionFailed) && error.is_a?(ActiveRecord::ConnectionFailed)
+      return true if defined?(ActiveRecord::QueryAborted) && error.is_a?(ActiveRecord::QueryAborted)
+      # A wait on a lock that the database's own lock timeout ended.
+      return true if error.is_a?(ActiveRecord::LockWaitTimeout)
+
+      cause = error.cause
+      code = if cause.respond_to?(:error_number) then cause.error_number
+      elsif cause.respond_to?(:error_code) then cause.error_code
+      end
+      TIMEOUT_CODES.include?(code)
+    end
+  end
+end