tina4ruby 3.13.93 → 3.13.96

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

data/lib/tina4/database_result.rb

@@ -8,7 +8,15 @@ module Tina4
     attr_reader :records, :columns, :count, :limit, :offset, :sql,
                 :affected_rows, :last_id, :error
 
-    def initialize(records = [], sql: "", columns: [], count: nil, limit: 10, offset: 0,
+    # `limit` is the row cap ACTUALLY APPLIED to the statement that produced
+    # these records — what Database#fetch appended — and `0` means none was
+    # (an explicit no-limit read, SQL carrying its own trailing LIMIT, or a
+    # write). The default used to be `10`: Database#fetch_direct never passed
+    # limit:/offset:, so that untouched default was reported on EVERY fetch
+    # whatever limit ran — and 10 is the stale v2 documentation number that the
+    # buried PHP row-cap test also asserted as the cap. 0 says "no cap recorded"
+    # instead of quietly naming a number nothing applied.
+    def initialize(records = [], sql: "", columns: [], count: nil, limit: 0, offset: 0,
                    affected_rows: 0, last_id: nil, error: nil, db: nil)
       @records = records || []
       @sql = sql
@@ -91,26 +99,60 @@ module Tina4
       lines.join("\n")
     end
 
-    def to_paginate(page: nil, per_page: nil)
-      per_page ||= @limit > 0 ? @limit : 10
-      page ||= @offset > 0 ? (@offset / per_page) + 1 : 1
-      total = @count
-      total_pages = [1, (total.to_f / per_page).ceil].max
-      slice_offset = (page - 1) * per_page
-      page_records = @records[slice_offset, per_page] || []
+    # Describe the page this result already IS. Takes NO arguments (ADR-0043).
+    #
+    # Every field is derived from the query that produced this result:
+    #   per_page    = the query's limit
+    #   page        = floor(offset / limit) + 1
+    #   total       = the true total for the filter (@count, from the COUNT probe
+    #                 Database#fetch runs when it applied the limit), NEVER the
+    #                 number of rows this page returned
+    #   total_pages = ceil(total / per_page)
+    #   records     = the rows the query returned, VERBATIM, never re-sliced
+    #   limit/offset= the SQL limit/offset actually applied
+    #
+    # The envelope is EXACTLY seven snake_case keys, identical in all four
+    # frameworks: records, total, page, per_page, total_pages, limit, offset. The
+    # old duplicate/camelCase spellings (data, count, totalPages, has_next,
+    # has_prev) are gone - a JSON key is data and does not change spelling by host
+    # language, so the same integer never ships twice under two names.
+    #
+    # PASSING ANY ARGUMENT RAISES. A DatabaseResult holds no connection, so an
+    # argument could only re-slice rows already in memory and then report
+    # total_pages for pages it can never reach. To read page N, FETCH page N
+    # (limit + offset) and call this with no arguments. The removed page:/per_page:
+    # slicing mode is a hard error, never a silent reinterpretation - superseding
+    # the in-memory slice GitHub #106 asked for.
+    #
+    # MEASURED 2026-08-05 on a real 250-row table read with limit=20 offset=40
+    # (page 3 of 13): the old two-mode method re-sliced @records by the ABSOLUTE
+    # offset (40) against an array already only 20 long and returned ZERO records
+    # for a valid page, while still shipping a page number and total - an envelope
+    # that looked authoritative and was empty.
+    def to_paginate(*args, **kwargs)
+      unless args.empty? && kwargs.empty?
+        raise ArgumentError,
+              "to_paginate takes no arguments (ADR-0043): it describes the page " \
+              "this result already IS, derived from the query that produced it. A " \
+              "DatabaseResult holds no connection, so an argument could only " \
+              "re-slice rows already in memory and lie about total_pages. To read " \
+              "another page, FETCH it - fetch(sql, limit: per_page, offset: " \
+              "(page - 1) * per_page) - then call to_paginate with no arguments."
+      end
+
+      per_page    = @limit.to_i > 0 ? @limit.to_i : @records.size
+      page        = per_page > 0 ? (@offset.to_i / per_page) + 1 : 1
+      total       = @count
+      total_pages = per_page > 0 ? [1, (total.to_f / per_page).ceil].max : 1
+
       {
-        records: page_records,
-        data: page_records,
-        count: total,
+        records: @records,
         total: total,
-        limit: per_page,
-        offset: (page - 1) * per_page,
         page: page,
         per_page: per_page,
-        totalPages: total_pages,
         total_pages: total_pages,
-        has_next: page < total_pages,
-        has_prev: page > 1
+        limit: per_page,
+        offset: @offset.to_i
       }
     end
 
@@ -179,7 +221,11 @@ module Tina4
           size: size,
           decimals: decimals,
           nullable: col.key?(:nullable) ? col[:nullable] : (col.key?("nullable") ? col["nullable"] : true),
-          primary_key: col[:primary_key] || col["primary_key"] || col[:primary] || col["primary"] || false
+          # Symbol OR string key, because a driver row may arrive either way.
+          # The `:primary` / `"primary"` fallbacks that used to sit here were
+          # dead: no Ruby driver has ever emitted that spelling. It was mirroring
+          # PHP's odd `primary`, which PHP itself has now dropped for `primaryKey`.
+          primary_key: col[:primary_key] || col["primary_key"] || false
         }
       end
     end

data/lib/tina4/database_url.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Tina4
+  # A parsed database connection URL, as a VALUE.
+  #
+  # Feature 5 of the feature audit. Ruby had no parser to call: URL handling was
+  # inline in +Database#initialize+, so a URL could not be parsed without
+  # building a connection object. The parse could not be unit tested on its own,
+  # the four frameworks could not be compared without standing up a database,
+  # and +tina4 doctor+ or the setup wizard had nothing to call to validate a URL
+  # before using it.
+  #
+  # What was there instead was +detect_driver+: substring regex matching over the
+  # whole connection string with a silent <tt>else "sqlite"</tt> fallback, so 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. This class raises instead.
+  #
+  # Core Principle 6 says a connection string must mean literally the same thing
+  # in every framework. +spec/fixtures/database_url_corpus.json+ is the answer
+  # key, byte-identical in all four.
+  # DISPLAY REDACTS, FIDELITY DOES NOT. #inspect, #to_s and #to_safe_string
+  # replace the password with the redaction marker, so a log line, a backtrace or
+  # a status payload is safe. Marshal deliberately does not: its contract is a
+  # faithful round trip, and a masked Marshal would load an object whose password
+  # is the literal "***".
+  #
+  # The consequence: DO NOT PERSIST THIS OBJECT. A DatabaseUrl marshalled into a
+  # cache, a session or a queue payload puts the password in cleartext on disk.
+  # Record #to_safe_string instead. spec/database_url_redaction_spec.rb fails the
+  # build if framework code ever marshals one.
+  class DatabaseUrl
+    # URL scheme to CANONICAL engine. Aliases resolve ONCE, here, so nothing
+    # downstream ever compares raw schemes.
+    #
+    # +sqlite3+ is accepted because the driver is literally named sqlite3 in
+    # every framework (Python's sqlite3 module, Ruby's sqlite3 gem, PHP's
+    # ext-sqlite3, Node's node:sqlite), so people type it. The "3" is a
+    # file-format version, not a different engine, which is why the canonical
+    # name stays +sqlite+.
+    ENGINE_ALIASES = {
+      "sqlite" => "sqlite",
+      "sqlite3" => "sqlite",
+      "postgres" => "postgres",
+      "postgresql" => "postgres",
+      "pgsql" => "postgres",
+      "mysql" => "mysql",
+      "mssql" => "mssql",
+      "sqlserver" => "mssql",
+      "firebird" => "firebird",
+      "mongodb" => "mongodb",
+      "mongo" => "mongodb",
+      "odbc" => "odbc"
+    }.freeze
+
+    # Applied AT PARSE. The port is part of our contract, not the driver's
+    # business: a URL with no port must yield the same struct in all four.
+    DEFAULT_PORTS = {
+      "postgres" => 5432,
+      "mysql" => 3306,
+      "mssql" => 1433,
+      "firebird" => 3050,
+      "mongodb" => 27017
+    }.freeze
+
+    # What replaces a credential everywhere. One spelling, so a test can assert
+    # on it and a reader recognises it on sight.
+    REDACTED = "***"
+
+    # RFC 3986 scheme grammar. A scheme cannot contain ":", "@", "/" or a space,
+    # which is what makes it the ONLY part of an unparseable string that is
+    # provably not a password.
+    SCHEME = /\A[A-Za-z][A-Za-z0-9+.\-]*\z/.freeze
+
+    # host[:port][/path] with a NUMERIC port. The digit requirement is what does
+    # the work: it is why "user:secret" (a URL with the host left off) fails to
+    # match and gets redacted, while "192.168.88.99:55432/tina4_py" is echoed.
+    HOST_PORT = %r{\A(?:\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9._-]+)(?::\d+)?(?:/.*)?\z}m.freeze
+
+    # Credential KEYWORDS in the two keyword=value forms that carry one: the
+    # ODBC connection string (";"-separated) and the libpq/JDBC query string
+    # ("&"-separated). A braced value is matched FIRST because an ODBC value
+    # containing ";" must be braced - stopping at the ";" would leave the tail
+    # of the password in the output, which is exactly the bug shape this file
+    # exists to close.
+    #
+    # UID/USER are deliberately NOT redacted: a username is not a secret, and it
+    # is most of what makes a failed connection diagnosable.
+    CREDENTIAL_KEYWORDS = /\b(PWD|PASSWORD)\s*=\s*(?:\{[^}]*\}|[^;&]*)/i.freeze
+
+    attr_reader :engine, :host, :port, :database, :username, :password,
+                :connection_string
+
+    def initialize(url, username: nil, password: nil)
+      raise ArgumentError, "DatabaseUrl: the URL is empty" if url.nil? || url.to_s.strip.empty?
+
+      url = url.to_s
+      @host = nil
+      @port = nil
+      @database = ""
+      @username = nil
+      @password = nil
+      @connection_string = nil
+
+      if url.start_with?("sqlite:", "sqlite3:")
+        parse_sqlite(url)
+      elsif url.start_with?("odbc:///")
+        @engine = "odbc"
+        @connection_string = url[("odbc:///".length)..]
+      else
+        parse_standard(url)
+      end
+
+      # Separate credentials fill in only when the URL carried NONE.
+      #
+      # ABSENT and BLANK are different values, and the difference is load
+      # bearing: the gate is `nil?`, never `empty?`. A URL written
+      #   postgres://user:@host/db
+      # states an explicitly EMPTY password, so the TINA4_DATABASE_PASSWORD
+      # fallback must NOT fire; only
+      #   postgres://user@host/db
+      # is absent and takes the env value. Measured 2026-08-02: Ruby and PHP
+      # obey this, Python and Node return None for the blank form and therefore
+      # authenticate with a DIFFERENT password off the SAME .env - which is the
+      # kind of divergence nobody notices until an account locks out.
+      @username = username if @username.nil? && username && !username.empty?
+      @password = password if @password.nil? && password && !password.empty?
+    end
+
+    # Parse the configured URL, or nil when the variable is not set.
+    def self.from_env(key = "TINA4_DATABASE_URL")
+      url = (ENV[key] || "").strip
+      return nil if url.empty?
+
+      new(url, username: ENV["TINA4_DATABASE_USERNAME"], password: ENV["TINA4_DATABASE_PASSWORD"])
+    end
+
+    # THE redaction primitive. Every connection string that is about to reach a
+    # log line, an exception message or a dump goes through here.
+    #
+    # It takes a RAW string and never raises, because the paths that most need
+    # redacting are exactly the ones where parsing already failed.
+    #
+    # Measured in this repo on 2026-08-02, before this existed:
+    #   * Database#safe_connection_target carried its OWN regex, and
+    #       postgres://u:p@ss@h:5432/db -> postgres://u:***@ss@h:5432/db
+    #     leaked the password tail past the first "@" (the Ruby twin of the PHP
+    #     `password=\S*` tail leak), and
+    #       odbc:///...;PWD=<secret>    -> returned VERBATIM
+    #     went straight into DatabaseConnectionError, which is raised at the
+    #     first query and lands in a 500 body.
+    #   * DatabaseUrl's own invalid-URL ArgumentError interpolated the whole raw
+    #     URL, and detect_driver raises it on the BOOT path, so one typo in
+    #     TINA4_DATABASE_URL wrote the password into the boot log and CI output.
+    # One primitive means the next such bug is fixed once, not four times.
+    def self.redact(raw)
+      text = raw.to_s
+      return "" if text.empty?
+
+      begin
+        # A URL that PARSES gets the round-tripping form rebuilt from the parsed
+        # FIELDS. That form cannot leak: the password is never copied into it.
+        new(text).to_safe_string
+      rescue StandardError
+        # Unparseable - fall back to the structural scrub. Redaction must never
+        # raise; a raise here would mask the error we were called to describe.
+        scrub(text)
+      end
+    end
+
+    # Structural redaction of a string that did NOT parse.
+    def self.scrub(text)
+      head, separator, rest = text.to_s.partition("://")
+
+      # No "://" - a bare file path, or an ODBC/keyword string. There is no
+      # userinfo to find, so only the keyword form can hide a secret here.
+      return scrub_keywords(text.to_s) if separator.empty?
+
+      # A head that is not a scheme is unknown text, and unknown text may BE the
+      # secret (the measured Python case was `notaurl-with-SuperSecret123`).
+      # Say nothing about it rather than guess.
+      return REDACTED unless head.match?(SCHEME)
+
+      # The authority is taken to the first "?" or "#", NOT to the first "/".
+      # An unencoded "/" inside a password would otherwise cut the region short,
+      # push the "@" outside it, and let the password prefix survive.
+      cut = rest.index(/[?#]/) || rest.length
+      "#{head}://#{redact_authority(rest[0, cut])}#{scrub_keywords(rest[cut..].to_s)}"
+    end
+
+    # Take the credential out of a URL authority.
+    #
+    #   user:pass@host:5432/db -> user:***@host:5432/db
+    #   host:5432/db           -> host:5432/db   (no credential present)
+    #   user:pass              -> user:***       (host left off - a real typo,
+    #                                             and the only reason the no-"@"
+    #                                             branch cannot echo blindly)
+    def self.redact_authority(authority)
+      # The LAST "@", because userinfo ends at the last "@" (RFC 3986). Splitting
+      # on the FIRST one is how an unencoded "@" inside a password leaves a tail
+      # in the output.
+      at = authority.rindex("@")
+      if at
+        userinfo = authority[0, at]
+        host = authority[(at + 1)..].to_s
+        name, colon, = userinfo.partition(":")
+        return colon.empty? ? "#{name}@#{host}" : "#{name}:#{REDACTED}@#{host}"
+      end
+
+      return authority if authority.match?(HOST_PORT)
+
+      name, colon, = authority.partition(":")
+      colon.empty? ? name : "#{name}:#{REDACTED}"
+    end
+
+    # Redact the value side of a credential keyword, leaving every other
+    # keyword visible so the string is still diagnosable.
+    def self.scrub_keywords(text)
+      text.gsub(CREDENTIAL_KEYWORDS) { "#{Regexp.last_match(1)}=#{REDACTED}" }
+    end
+
+    # The invalid-URL message, with the credential taken OUT.
+    #
+    # It still has to be diagnosable, so it keeps the scheme, the host, the port
+    # as written (the usual fault) and the database name - only the password
+    # becomes ***. When the value has no "://" there is no structure to trust,
+    # so the value is not shown at all and the message says why.
+    def self.invalid_url_error(url)
+      text = url.to_s
+      if text.include?("://")
+        "DatabaseUrl: Invalid URL format '#{scrub(text)}' - expected " \
+          "scheme://user:password@host:port/database"
+      else
+        "DatabaseUrl: Invalid URL format - no '://', so there is no scheme to " \
+          "connect with. The URL itself is not shown because it can contain a " \
+          "password. Expected scheme://user:password@host:port/database"
+      end
+    end
+
+    # Connection target. sqlite and odbc are the whole value.
+    def dsn
+      return @database if @engine == "sqlite"
+      return @connection_string.to_s if @engine == "odbc"
+
+      out = @host.to_s
+      out += ":#{@port}" unless @port.nil?
+      out += "/#{@database}" unless @database.empty?
+      out
+    end
+
+    # The URL with the password replaced by <tt>***</tt>.
+    #
+    # The ONLY form allowed in a log line or an error message: a connection URL
+    # in a log is a credential leak. It round-trips the input, so it stays
+    # readable as well as safe.
+    def to_safe_string
+      return "sqlite:///#{@database}" if @engine == "sqlite"
+      # ODBC used to return the connection string VERBATIM here, PWD= included -
+      # measured 2026-08-02. The negative test "never leaks the password" passed
+      # anyway, because the shared corpus had no odbc row for it to check: the
+      # guard existed, the test was green, and it protected nothing. Every other
+      # keyword stays visible so a failed ODBC connection is still diagnosable.
+      return "odbc:///#{self.class.scrub_keywords(@connection_string.to_s)}" if @engine == "odbc"
+
+      out = "#{@engine}://"
+      unless @username.nil?
+        out += @username
+        out += ":***" unless @password.nil?
+        out += "@"
+      end
+      out += @host.to_s
+      out += ":#{@port}" unless @port.nil?
+      out += "/#{@database}" unless @database.empty?
+      out
+    end
+
+    # inspect lands in backtraces and the console, so it MUST be the safe form.
+    def inspect
+      "#<Tina4::DatabaseUrl #{to_safe_string}>"
+    end
+
+    # Interpolation ("connecting to #{url}") and JSON both have to be safe, not
+    # just inspect. Ruby's inspect already guarded the console and backtraces -
+    # these two close the same class of leak PHP has through print_r/var_dump
+    # and Node through JSON.stringify, and they make the useless default
+    # "#<Tina4::DatabaseUrl:0x000...>" say something instead.
+    def to_s
+      to_safe_string
+    end
+
+    def to_json(*args)
+      to_safe_string.to_json(*args)
+    end
+
+    private
+
+    # Strip EXACTLY ONE leading slash: the URL path separator, never more.
+    def strip_one_slash(path)
+      path.start_with?("/") ? path[1..] : path
+    end
+
+    # sqlite is parsed on the RAW string, never through URI. URI collapses
+    # "sqlite:/x" and "sqlite:///x", losing the difference between a one-slash
+    # ABSOLUTE path and the documented three-slash RELATIVE form.
+    #
+    #   sqlite:///app.db       -> app.db        (three slashes = relative)
+    #   sqlite:////abs/app.db  -> /abs/app.db   (four slashes = absolute)
+    #   sqlite:/abs/app.db     -> /abs/app.db   (one slash = a real absolute)
+    #   sqlite:app.db          -> app.db
+    def parse_sqlite(url)
+      @engine = "sqlite"
+      url = "sqlite:#{url[("sqlite3:".length)..]}" if url.start_with?("sqlite3:")
+
+      @database = if ["sqlite::memory:", "sqlite:///:memory:"].include?(url)
+                    ":memory:"
+                  elsif url.start_with?("sqlite:///")
+                    strip_one_slash(url[("sqlite://".length)..])
+                  elsif url.start_with?("sqlite://")
+                    url[("sqlite://".length)..]
+                  else
+                    url[("sqlite:".length)..]
+                  end
+    end
+
+    def parse_standard(url)
+      parsed = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        # NEVER interpolate the raw URL here. Measured 2026-08-02: a malformed
+        # TINA4_DATABASE_URL put the password verbatim into this ArgumentError,
+        # and Database#detect_driver raises it during boot - so the credential
+        # reached the boot log, the error overlay, a crash report and CI output.
+        raise ArgumentError, self.class.invalid_url_error(url)
+      end
+
+      scheme = parsed.scheme.to_s.downcase
+      raise ArgumentError, self.class.invalid_url_error(url) if scheme.empty?
+
+      engine = ENGINE_ALIASES[scheme]
+      if engine.nil?
+        raise ArgumentError,
+              "DatabaseUrl: Unsupported database scheme '#{scheme}'. " \
+              "Supported: #{ENGINE_ALIASES.keys.join(', ')}"
+      end
+
+      @engine = engine
+      @host = parsed.host && !parsed.host.empty? ? parsed.host : nil
+      @port = parsed.port || DEFAULT_PORTS[engine]
+      @username = parsed.user ? URI.decode_www_form_component(parsed.user) : nil
+      @password = parsed.password ? URI.decode_www_form_component(parsed.password) : nil
+
+      # Strip EXACTLY ONE leading slash - the URL path separator. Stripping every
+      # slash turns the documented absolute Firebird form
+      # `firebird://host:3050//var/lib/db.fdb` into the RELATIVE
+      # `var/lib/db.fdb`. Verified against live Firebird 5.0.4: the driver takes
+      # one or two leading slashes and rejects a relative path outright.
+      database = strip_one_slash(parsed.path.to_s)
+      @database = database.empty? && engine == "mongodb" ? "tina4" : database
+    end
+  end
+end

data/lib/tina4/dev.rb

@@ -3,7 +3,6 @@
 # Convenience require for all development/optional tools.
 # Usage: require "tina4/dev"
 
-require_relative "scss_compiler"
 require_relative "testing"
 require_relative "graphql"
 require_relative "websocket"