tina4ruby 3.13.37 → 3.13.39

data/lib/tina4/database.rb

@@ -199,19 +199,32 @@ module Tina4
       # commit/rollback clear it. While pinned, current_driver returns the same
       # driver for every call so the whole transaction runs on one connection.
       @tx_pin_key = :"tina4_pinned_adapter_#{object_id}"
-
-      # Query cache. One store, two layers (parity with Python connection.py):
-      #   • request-scoped (DEFAULT ON, off-switch TINA4_AUTO_CACHING=false) —
-      #     dedupes identical SELECTs to protect the DB from rapid repeat reads.
-      #     Cleared at the START of every HTTP request (so it never serves rows
-      #     across requests) AND on any write, with a short safety TTL (5s) for
-      #     non-request contexts (scripts/workers).
+      # Per-thread nested-transaction depth counter (DB-contract C, v3.13.37).
+      # A second start_transaction on a thread that already holds the pin is a
+      # double-begin: most engines silently commit or no-op the inner BEGIN,
+      # leaving the connection mid-transaction. We warn + increment depth instead
+      # of re-beginning; the inner commit just decrements; the outer commit/any
+      # rollback releases the pin.
+      @tx_depth_key = :"tina4_tx_depth_#{object_id}"
+
+      # Query cache. One store, two layers (parity with Python connection.py).
+      # BOTH layers are OPT-IN — the DEFAULT is OFF.
+      #
+      # A request-scoped cache that defaults ON is a footgun: a SELECT MAX(id)
+      # (or generator read) right before an INSERT in the SAME request returns a
+      # cached pre-write value → duplicate primary keys, and any read-after-write
+      # in one request shows stale state. So both layers default OFF:
+      #   • request-scoped (opt-in, TINA4_AUTO_CACHING=true) — dedupes identical
+      #     SELECTs to protect the DB from rapid repeat reads on read-heavy
+      #     endpoints. Cleared at the START of every HTTP request (so it never
+      #     serves rows across requests) AND on any write, with a short safety
+      #     TTL (5s) for non-request contexts (scripts/workers).
       #   • persistent (opt-in, TINA4_DB_CACHE=true) — cross-request TTL cache
       #     that is NOT cleared per request; entries expire by TINA4_DB_CACHE_TTL.
       @cache_persistent = truthy?(ENV["TINA4_DB_CACHE"])
-      # Default true; honour the same truthy semantics the framework uses
-      # (mirrors Python's is_truthy(get("TINA4_AUTO_CACHING", "true"))).
-      @cache_request_scoped = truthy?(ENV["TINA4_AUTO_CACHING"] || "true")
+      # Default OFF; honour the same truthy semantics the framework uses
+      # (mirrors Python's is_truthy(get("TINA4_AUTO_CACHING", "false"))).
+      @cache_request_scoped = truthy?(ENV["TINA4_AUTO_CACHING"] || "false")
       @cache_enabled = @cache_persistent || @cache_request_scoped
       @cache_ttl = if @cache_persistent
                      (ENV["TINA4_DB_CACHE_TTL"] || "30").to_i
@@ -242,6 +255,17 @@ module Tina4
         end
       end
 
+      # Autocommit is ON by default — parity with Python/PHP/Node. A standalone
+      # write (execute/insert/update/delete made OUTSIDE an explicit
+      # start_transaction()/commit() block) commits on its own connection before
+      # returning, so a write actually persists. An UNSET TINA4_AUTOCOMMIT is
+      # treated as TRUE; set TINA4_AUTOCOMMIT=false for strict manual mode (every
+      # write needs an explicit commit). Inside an explicit transaction the
+      # framework-issued commit is suppressed (gated on the thread tx-pin), so
+      # explicit transactions stay atomic. Mirrors Python's
+      # DatabaseAdapter._autocommit ("true"/"1"/"yes", default "true").
+      @autocommit = truthy?(ENV.fetch("TINA4_AUTOCOMMIT", "true"))
+
       # Register this connection so Tina4::Database.reset_request_caches can
       # clear its request-scoped entries at the start of every HTTP request.
       Tina4::Database.register_instance(self)
@@ -269,10 +293,11 @@ module Tina4
       @driver.connect(@connection_string, username: @username, password: @password)
       @connected = true
 
-      # Enable autocommit if TINA4_AUTOCOMMIT env var is set
-      if truthy?(ENV["TINA4_AUTOCOMMIT"]) && @driver.respond_to?(:autocommit=)
-        @driver.autocommit = true
-      end
+      # Push the resolved autocommit setting down to the driver when it exposes a
+      # 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=)
 
       Tina4::Log.info("Database connected: #{@driver_name}")
     rescue => e
@@ -374,6 +399,14 @@ module Tina4
 
     # Fetch rows with pagination, returning a DatabaseResult.
     #
+    # FAILS LOUD (v3.13.37, DB-contract A): a SQL error in the main query
+    # propagates — a typo'd / bad SELECT RAISES, it never silently returns an
+    # empty result. The cause is captured on @last_error / #get_error before the
+    # re-raise (parity with #execute and the Python master), so the public API
+    # can read why it failed even for engines whose driver doesn't expose its
+    # own last_error. Because the raise happens BEFORE cache_set is reached, a
+    # buried failure is never written into the query cache.
+    #
     # Pass `no_cache: true` to bypass the query cache entirely for this single
     # call — no lookup, no store — and run the query directly against the
     # driver. Works for both the request-scoped auto-cache and the persistent
@@ -404,22 +437,30 @@ module Tina4
           @cache_mutex.synchronize { @cache_hits += 1 }
           return cached
         end
-        result = drv.execute_query(effective_sql, params)
-        result = Tina4::DatabaseResult.new(result, sql: effective_sql, db: self)
+        # 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)
         cache_set(key, result)
         @cache_mutex.synchronize { @cache_misses += 1 }
         return result
       end
 
-      rows = drv.execute_query(effective_sql, params)
-      Tina4::DatabaseResult.new(rows, sql: effective_sql, db: self)
+      fetch_direct(drv, effective_sql, params)
     end
 
     # Fetch a single row (or nil).
     #
+    # FAILS LOUD (v3.13.37, DB-contract A): a SQL error RAISES and populates
+    # @last_error / #get_error the same way #execute and #fetch do — pre-fix
+    # fetch_one ran the query through #fetch but did not separately guarantee the
+    # error capture, and a buried failure could be cached as nil. It now routes
+    # the uncached path through fetch_one_direct (capture + re-raise) and, on the
+    # cached path, only ever stores a value produced by a SUCCESSFUL read.
+    #
     # Pass `no_cache: true` to bypass the query cache entirely for this call —
     # no lookup, no store — running the query directly. The `no_cache` flag is
-    # propagated to the inner #fetch so the request-scoped/persistent cache is
+    # propagated to the inner read so the request-scoped/persistent cache is
     # never populated either. Default `false` preserves cached behaviour.
     def fetch_one(sql, params = [], no_cache: false)
       sql = Tina4::Database.strip_trailing_semicolons(sql)
@@ -430,15 +471,15 @@ module Tina4
           @cache_mutex.synchronize { @cache_hits += 1 }
           return cached
         end
-        result = fetch(sql, params, limit: 1)
-        value = result.first
+        # Raises (and captures @last_error) BEFORE cache_set, so a failed read
+        # is never cached as nil.
+        value = fetch_one_direct(sql, params)
         cache_set(key, value)
         @cache_mutex.synchronize { @cache_misses += 1 }
         return value
       end
 
-      result = fetch(sql, params, limit: 1, no_cache: no_cache)
-      result.first
+      fetch_one_direct(sql, params)
     end
 
     def insert(table, data)
@@ -459,7 +500,9 @@ module Tina4
       placeholders = drv.placeholders(columns.length)
       sql = "INSERT INTO #{table} (#{columns.join(', ')}) VALUES (#{placeholders})"
       drv.execute(sql, data.values)
-      { success: true, last_id: drv.last_insert_id }
+      last_id = drv.last_insert_id
+      autocommit_standalone_write(drv)
+      { success: true, last_id: last_id }
     end
 
     def update(table, data, filter = {}, params = nil)
@@ -472,6 +515,7 @@ module Tina4
         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 { success: true }
       end
 
@@ -481,6 +525,7 @@ module Tina4
       sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
       values = data.values + filter.values
       drv.execute(sql, values)
+      autocommit_standalone_write(drv)
       { success: true }
     end
 
@@ -499,6 +544,7 @@ module Tina4
         sql = "DELETE FROM #{table}"
         sql += " WHERE #{filter}" unless filter.empty?
         drv.execute(sql, Array(params))
+        autocommit_standalone_write(drv)
         return { success: true }
       end
 
@@ -507,6 +553,7 @@ module Tina4
       sql = "DELETE FROM #{table}"
       sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
       drv.execute(sql, filter.values)
+      autocommit_standalone_write(drv)
       { success: true }
     end
 
@@ -534,12 +581,29 @@ module Tina4
       @driver_name
     end
 
-    # Execute a write statement. Returns true/false for simple writes.
-    # Returns DatabaseResult if SQL contains RETURNING, CALL, EXEC, or SELECT.
+    # Execute a write statement. FAILS LOUD — raises on a SQL error.
+    #
+    # On a SQL error (bad SQL, constraint violation, dead/aborted connection,
+    # missing driver) the cause is captured on @last_error / #get_error AND the
+    # error is re-raised — execute() never silently returns false on failure.
+    # Almost no caller checks a boolean after every write, so the old
+    # swallow-and-return-false behaviour turned a failed INSERT/UPDATE/DELETE
+    # into a silent partial-write footgun. This mirrors fetch()/fetch_one(),
+    # which already raise, and the Python master (database.execute).
+    #
+    # On SUCCESS the return is unchanged: a DatabaseResult when the SQL contains
+    # RETURNING, CALL, EXEC, or SELECT (truthy), otherwise true. Never false.
+    #
+    # Higher-level callers that promise a boolean (ORM save/create_table) wrap
+    # this in begin/rescue and return false themselves; the migration runner and
+    # dev-admin/MCP DB tools catch the raise and surface it as a failed migration
+    # or a clean { error: } payload respectively.
     def execute(sql, params = [])
       cache_invalidate if @cache_enabled
-      result = current_driver.execute(sql, params)
+      drv = current_driver
+      result = drv.execute(sql, params)
       @last_error = nil
+      autocommit_standalone_write(drv)
       sql_upper = sql.strip.upcase
       if sql_upper.include?("RETURNING") || sql_upper.start_with?("CALL ") ||
          sql_upper.start_with?("EXEC ") || sql_upper.start_with?("SELECT ")
@@ -548,7 +612,7 @@ module Tina4
       true
     rescue => e
       @last_error = e.message
-      false
+      raise
     end
 
     def execute_many(sql, params_list = [])
@@ -570,6 +634,7 @@ module Tina4
     def transaction
       drv = current_driver
       Thread.current[@tx_pin_key] = drv
+      Thread.current[@tx_depth_key] = 1
       drv.begin_transaction
       yield self
       drv.commit
@@ -578,29 +643,83 @@ module Tina4
       raise e
     ensure
       Thread.current[@tx_pin_key] = nil
+      Thread.current[@tx_depth_key] = nil
     end
 
     # Begin a transaction without a block — matches PHP/Python/Node API.
     # Pins the driver to this thread for the whole transaction so executes
     # and the final commit/rollback all run on the same connection.
+    #
+    # Nested-begin guard (v3.13.37, DB-contract C): a second start_transaction
+    # on a thread that already holds the pin is a double-begin — the inner BEGIN
+    # silently commits or no-ops on most engines, leaving the connection
+    # mid-transaction with the caller none the wiser. We keep a per-thread depth
+    # counter and log a clear warning instead of silently re-beginning. The pin
+    # stays on the original driver so commit/rollback still land on the right
+    # connection.
     def start_transaction
+      pinned = Thread.current[@tx_pin_key]
+      if pinned
+        depth = (Thread.current[@tx_depth_key] || 1)
+        Tina4::Log.warning(
+          "start_transaction called while a transaction is already open on this " \
+          "thread (depth would become #{depth + 1}). Nested transactions are not " \
+          "supported — the existing transaction stays open on its pinned " \
+          "connection and this nested begin is ignored. Commit or rollback the " \
+          "outer transaction first."
+        )
+        Thread.current[@tx_depth_key] = depth + 1
+        return
+      end
       drv = current_driver
       Thread.current[@tx_pin_key] = drv
+      Thread.current[@tx_depth_key] = 1
       drv.begin_transaction
     end
 
     # Commit the current transaction and release the driver pin.
+    #
+    # FAILS LOUD (v3.13.37, DB-contract C): if the underlying commit raises,
+    # capture @last_error and RE-RAISE — never swallow. On failure the
+    # transaction pin is RETAINED so the caller's follow-up #rollback lands on
+    # the SAME connection (clearing it would leak a dirty connection back into
+    # the pool and route the rollback to a different one). The pin is cleared
+    # ONLY on a successful commit. An inner commit of an ignored nested begin
+    # (depth > 1) just decrements the depth and returns — the outer commit is
+    # the real one.
     def commit
+      depth = (Thread.current[@tx_depth_key] || 0)
+      if depth > 1
+        Thread.current[@tx_depth_key] = depth - 1
+        return
+      end
       current_driver.commit
-    ensure
+      @last_error = nil
+      # Success — release the pin.
       Thread.current[@tx_pin_key] = nil
+      Thread.current[@tx_depth_key] = nil
+    rescue => e
+      # Keep the pin so rollback reaches this same connection.
+      @last_error = e.message
+      raise
     end
 
     # Roll back the current transaction and release the driver pin.
+    #
+    # Rollback is the terminal cleanup of a transaction, so it ALWAYS clears the
+    # pin (and the depth counter) — even after a failed commit it routes to the
+    # retained pinned connection and cleans it up. If the underlying rollback
+    # itself raises, @last_error is captured and the error re-raised, but the pin
+    # is still released so a poisoned connection doesn't stay pinned forever.
     def rollback
       current_driver.rollback
+      @last_error = nil
+    rescue => e
+      @last_error = e.message
+      raise
     ensure
       Thread.current[@tx_pin_key] = nil
+      Thread.current[@tx_depth_key] = nil
     end
 
     def tables
@@ -733,6 +852,46 @@ module Tina4
 
     private
 
+    # Run a fetch straight against the driver — no cache lookup or store.
+    #
+    # DB-contract A (v3.13.37): shared by the cached and no_cache paths so error
+    # capture is identical regardless of caching. FAILS LOUD: a SQL error in the
+    # 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)
+      result = drv.execute_query(effective_sql, params)
+      @last_error = nil
+      Tina4::DatabaseResult.new(result, sql: effective_sql, db: self)
+    rescue => e
+      @last_error = driver_error_message(drv, e)
+      raise
+    end
+
+    # Run a fetch_one straight against the driver — no cache lookup or store.
+    #
+    # DB-contract A (v3.13.37): goes through #fetch (so the trailing-semicolon
+    # strip + LIMIT-append + driver path stay identical), but wraps it so the
+    # error is captured on @last_error and re-raised. Returns the first row (a
+    # Hash) or nil on a SUCCESSFUL "no row" read.
+    def fetch_one_direct(sql, params)
+      result = fetch(sql, params, limit: 1, no_cache: true)
+      @last_error = nil
+      result.first
+    rescue => e
+      @last_error = driver_error_message(current_driver, e)
+      raise
+    end
+
+    # 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
+      msg = drv_err || error.message
+      msg = error.message if msg.nil? || msg.to_s.empty?
+      msg || @last_error
+    end
+
     # Ensure the tina4_sequences table exists for race-safe ID generation.
     def ensure_sequence_table
       return if table_exists?("tina4_sequences")
@@ -747,41 +906,212 @@ module Tina4
     end
 
     # Atomically increment and return the next value for a named sequence.
-    # Seeds from MAX(pk_column) on first use so existing data is respected.
+    #
+    # DB-contract B (v3.13.37): the old read-increment-read path had a RACE —
+    # two concurrent callers could read the same current_value and return the
+    # same id (duplicate primary keys). Each engine now uses a single atomic
+    # increment-and-return, pinned to ONE driver so the two statements (where two
+    # are needed) land on the same connection:
+    #
+    #   * SQLite (lib >= 3.35): UPDATE ... SET current_value = current_value + 1
+    #     WHERE seq_name = ? RETURNING current_value — one atomic statement, run
+    #     under the process-wide SqliteDriver.write_lock. Older SQLite falls back
+    #     to UPDATE +1 then SELECT, still serialised by the held write_lock.
+    #   * MySQL: UPDATE ... SET current_value = LAST_INSERT_ID(current_value + 1)
+    #     then SELECT LAST_INSERT_ID() on the SAME connection (per-connection →
+    #     race-safe).
+    #   * MSSQL: UPDATE ... SET current_value += 1 OUTPUT inserted.current_value
+    #     WHERE seq_name = ? — one atomic statement.
+    #
+    # Seeding is race-safe: an atomic insert-if-absent (INSERT OR IGNORE /
+    # INSERT IGNORE / INSERT ... WHERE NOT EXISTS) seeded from MAX(pk) runs BEFORE
+    # the atomic increment, so there is never a read-then-insert gap. On error we
+    # RAISE (never silently fall back to 1).
     def sequence_next(seq_name, table: nil, pk_column: "id")
-      ensure_sequence_table
+      # Pin a single driver for the whole sequence op so seed + increment + read
+      # all hit the SAME connection. Inside an active transaction the driver is
+      # already pinned; otherwise pin here and release in the ensure so the pool
+      # can rotate afterwards.
+      already_pinned = !Thread.current[@tx_pin_key].nil?
       drv = current_driver
+      Thread.current[@tx_pin_key] = drv unless already_pinned
 
-      # Check if the sequence key already exists
-      rows = drv.execute_query("SELECT current_value FROM tina4_sequences WHERE seq_name = ?", [seq_name])
-      row = rows.is_a?(Array) ? rows.first : nil
+      begin
+        case @driver_name
+        when "sqlite"
+          # SQLite does ensure-table + seed + increment all under the driver
+          # write lock (a single shared connection — concurrent reads/writes on
+          # it otherwise corrupt or race).
+          sequence_next_sqlite(drv, seq_name, table, pk_column)
+        when "mysql"
+          ensure_sequence_table
+          sequence_next_mysql(drv, seq_name, table, pk_column)
+        when "mssql"
+          ensure_sequence_table
+          sequence_next_mssql(drv, seq_name, table, pk_column)
+        else
+          # Any other engine routed here (defensive) — generic atomic-ish path.
+          ensure_sequence_table
+          sequence_next_generic(drv, seq_name, table, pk_column)
+        end
+      ensure
+        Thread.current[@tx_pin_key] = nil unless already_pinned
+      end
+    end
 
-      if row.nil?
-        # Seed from MAX(pk_column) if table data exists
-        seed_value = 0
-        if table
-          begin
-            max_rows = drv.execute_query("SELECT MAX(#{pk_column}) AS max_id FROM #{table}")
-            max_row = max_rows.is_a?(Array) ? max_rows.first : nil
-            val = row_value(max_row, :max_id)
-            seed_value = val.to_i if val
-          rescue
-            # Table may not exist yet — start from 0
-          end
+    # Best-effort MAX(pk) seed for a new sequence row. 0 if table missing/empty.
+    def sequence_seed_value(drv, table, pk_column)
+      return 0 unless table
+
+      max_rows = drv.execute_query("SELECT MAX(#{pk_column}) AS max_id FROM #{table}")
+      max_row = max_rows.is_a?(Array) ? max_rows.first : nil
+      val = row_value(max_row, :max_id)
+      val ? val.to_i : 0
+    rescue StandardError
+      0  # Table doesn't exist yet — start at 0
+    end
+
+    # SQLite atomic increment. Holds the process-wide write lock for the ENTIRE
+    # op (ensure-table + seed + increment). The single UPDATE ... RETURNING (lib
+    # >= 3.35) is itself atomic; the held lock serialises every connection touch
+    # so no duplicate ids under concurrency. ensure-table is done inline under the
+    # 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
+      raise "get_next_id: SQLite driver has no live connection" if conn.nil?
+
+      Tina4::Drivers::SqliteDriver.write_lock.synchronize do
+        # Ensure the sequence table exists (idempotent) on this connection.
+        conn.execute(
+          "CREATE TABLE IF NOT EXISTS tina4_sequences (" \
+          "seq_name VARCHAR(200) NOT NULL PRIMARY KEY, " \
+          "current_value INTEGER NOT NULL DEFAULT 0)"
+        )
+        seed = sequence_seed_value(drv, table, pk_column)
+        conn.execute(
+          "INSERT OR IGNORE INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)",
+          [seq_name, seed]
+        )
+
+        if sqlite_supports_returning?
+          # One atomic increment-and-return.
+          rows = conn.execute(
+            "UPDATE tina4_sequences SET current_value = current_value + 1 " \
+            "WHERE seq_name = ? RETURNING current_value",
+            [seq_name]
+          )
+          row = rows.is_a?(Array) ? rows.first : nil
+        else
+          # Older SQLite (< 3.35, no RETURNING): increment then read. Still
+          # race-safe because we hold write_lock across both statements.
+          conn.execute(
+            "UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?",
+            [seq_name]
+          )
+          rows = conn.execute(
+            "SELECT current_value FROM tina4_sequences WHERE seq_name = ?",
+            [seq_name]
+          )
+          row = rows.is_a?(Array) ? rows.first : nil
         end
-        drv.execute("INSERT INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)", [seq_name, seed_value])
-        drv.commit rescue nil
+
+        val = sqlite_row_value(row, "current_value")
+        raise "get_next_id: sequence row '#{seq_name}' vanished mid-increment" if val.nil?
+
+        val.to_i
       end
+    end
 
-      # Atomic increment
-      drv.execute("UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?", [seq_name])
+    # MySQL atomic increment. LAST_INSERT_ID(expr) stashes expr in this
+    # CONNECTION's session var and returns it — atomic per-connection, no
+    # read-back race. Calls the driver directly (not self.commit) so it doesn't
+    # trip Database#commit's pin management.
+    def sequence_next_mysql(drv, seq_name, table, pk_column)
+      seed = sequence_seed_value(drv, table, pk_column)
+      # Race-safe seed: INSERT IGNORE is a no-op if the row exists.
+      drv.execute("INSERT IGNORE INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)", [seq_name, seed])
+      drv.commit rescue nil
+      drv.execute(
+        "UPDATE tina4_sequences SET current_value = LAST_INSERT_ID(current_value + 1) WHERE seq_name = ?",
+        [seq_name]
+      )
       drv.commit rescue nil
+      rows = drv.execute_query("SELECT LAST_INSERT_ID() AS next_id")
+      row = rows.is_a?(Array) ? rows.first : nil
+      val = row_value(row, :next_id)
+      raise "get_next_id: LAST_INSERT_ID() returned nothing for '#{seq_name}'" if val.nil?
 
-      # Read back the incremented value
+      val.to_i
+    end
+
+    # MSSQL atomic increment via a single UPDATE ... OUTPUT statement.
+    def sequence_next_mssql(drv, seq_name, table, pk_column)
+      seed = sequence_seed_value(drv, table, pk_column)
+      # Race-safe seed: INSERT only when absent (single statement).
+      drv.execute(
+        "INSERT INTO tina4_sequences (seq_name, current_value) " \
+        "SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM tina4_sequences WHERE seq_name = ?)",
+        [seq_name, seed, seq_name]
+      )
+      drv.commit rescue nil
+      # Single atomic statement: increment + return the new value via OUTPUT.
+      rows = drv.execute_query(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 " \
+        "OUTPUT inserted.current_value AS next_id WHERE seq_name = ?",
+        [seq_name]
+      )
+      drv.commit rescue nil
+      row = rows.is_a?(Array) ? rows.first : nil
+      val = row_value(row, :next_id)
+      raise "get_next_id: OUTPUT produced no row for sequence '#{seq_name}'" if val.nil?
+
+      val.to_i
+    end
+
+    # Defensive fallback for any engine not otherwise special-cased: seed if
+    # absent (rollback on conflict), increment, then read on the pinned driver.
+    def sequence_next_generic(drv, seq_name, table, pk_column)
+      seed = sequence_seed_value(drv, table, pk_column)
+      begin
+        drv.execute("INSERT INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)", [seq_name, seed])
+        drv.commit rescue nil
+      rescue StandardError
+        # Row likely already exists (PK conflict) — fine, keep going.
+        drv.rollback rescue nil
+      end
+      drv.execute("UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?", [seq_name])
+      drv.commit rescue nil
       rows = drv.execute_query("SELECT current_value FROM tina4_sequences WHERE seq_name = ?", [seq_name])
       row = rows.is_a?(Array) ? rows.first : nil
       val = row_value(row, :current_value)
-      val ? val.to_i : 1
+      raise "get_next_id: sequence row '#{seq_name}' missing" if val.nil?
+
+      val.to_i
+    end
+
+    # Whether the loaded SQLite library supports the RETURNING clause (>= 3.35).
+    def sqlite_supports_returning?
+      return @sqlite_returning unless @sqlite_returning.nil?
+
+      ver = (defined?(SQLite3::SQLITE_VERSION) && SQLite3::SQLITE_VERSION) || "0.0.0"
+      parts = ver.split(".").map(&:to_i)
+      major, minor = parts[0].to_i, parts[1].to_i
+      @sqlite_returning = (major > 3) || (major == 3 && minor >= 35)
+    rescue StandardError
+      @sqlite_returning = false
+    end
+
+    # Read a value from a raw sqlite3 row (results_as_hash → string keys; a bare
+    # RETURNING row may come back as a positional Array on some gem versions).
+    def sqlite_row_value(row, key)
+      return nil if row.nil?
+
+      if row.is_a?(Hash)
+        row[key] || row[key.to_sym] || row.values.first
+      elsif row.is_a?(Array)
+        row.first
+      end
     end
 
     # Safely extract a value from a driver result row, trying both symbol and string keys.
@@ -794,6 +1124,31 @@ module Tina4
       %w[true 1 yes on].include?((val || "").to_s.strip.downcase)
     end
 
+    # Durability: commit a standalone write so it actually persists.
+    #
+    # Called after a write (execute/insert/update/delete) issued OUTSIDE an
+    # explicit transaction. The commit is suppressed when autocommit is off
+    # (TINA4_AUTOCOMMIT=false, strict manual mode) OR when a transaction is open
+    # on this thread (the thread tx-pin is set) — so an explicit
+    # start_transaction()/commit() block stays atomic and is never broken up by
+    # a per-statement commit. A commit with no transaction in progress is a
+    # harmless no-op on every engine (SQLite swallows the specific
+    # "no transaction is active" error in its driver; PostgreSQL/MySQL/MSSQL emit
+    # at most a benign warning), so this never raises in the common case. Mirrors
+    # the `not self._in_transaction and self.autocommit` gate in the Python
+    # master and PHP's `autoCommit && transaction === null`.
+    def autocommit_standalone_write(drv)
+      return unless @autocommit
+      return unless Thread.current[@tx_pin_key].nil?
+
+      drv.commit
+    rescue StandardError => e
+      # A standalone write already succeeded; a follow-up commit failure here
+      # must not mask that. Capture for #get_error and log, but don't raise.
+      @last_error = e.message
+      Tina4::Log.warning("autocommit commit after standalone write failed: #{e.message}")
+    end
+
     # "persistent" / "request" / "off" — mirrors Python connection.py.
     def cache_mode
       if @cache_persistent