tina4ruby 3.13.137 → 3.13.138

data/lib/tina4/database.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 require "uri"
 require "digest"
@@ -27,28 +33,49 @@ module Tina4
       @password = password
       @drivers = Array.new(pool_size)  # nil slots — lazy creation
       @index = 0
+      @owners = {}
       @mutex = Mutex.new
     end
 
-    # Get the next driver via round-robin. Thread-safe.
+    # A lease belongs to one thread until checkin; rotating never exposes a
+    # connection with another caller's uncommitted work. Exhaustion is immediate
+    # so a synchronous caller cannot deadlock waiting on its own transaction.
     def checkout
       @mutex.synchronize do
-        idx = @index
-        @index = (@index + 1) % @pool_size
-
-        if @drivers[idx].nil?
-          driver = @driver_factory.call
-          driver.connect(@connection_string, username: @username, password: @password)
-          @drivers[idx] = driver
+        @pool_size.times do
+          idx = @index
+          @index = (@index + 1) % @pool_size
+          next if @owners.key?(idx)
+          unless @drivers[idx]
+            driver = @driver_factory.call
+            driver.connect(@connection_string, username: @username, password: @password)
+            @drivers[idx] = driver
+          end
+          @owners[idx] = Thread.current
+          return @drivers[idx]
         end
-
-        @drivers[idx]
+        raise "Database connection pool exhausted"
       end
     end
 
-    # Return a driver to the pool. Currently a no-op for round-robin.
-    def checkin(_driver)
-      # no-op
+    # Compatibility getter for adapter metadata. It never exposes a leased
+    # connection; callers performing driver I/O directly must checkout/checkin.
+    def peek
+      driver = checkout
+      checkin(driver)
+      driver
+    end
+
+    def checkin(driver, discard: false)
+      @mutex.synchronize do
+        idx = @drivers.index { |candidate| candidate.equal?(driver) }
+        raise ArgumentError, "Driver is not leased by this thread" unless idx && @owners[idx].equal?(Thread.current)
+        if discard
+          driver.close rescue nil
+          @drivers[idx] = nil
+        end
+        @owners.delete(idx)
+      end
     end
 
     # Close all active connections.
@@ -60,6 +87,7 @@ module Tina4
             @drivers[i] = nil
           end
         end
+        @owners.clear
       end
     end
 
@@ -250,6 +278,87 @@ module Tina4
       TRAILING_LIMIT_RE.match?(scrub_sql_text(sql))
     end
 
+    # Strip a trailing TOP-LEVEL ORDER BY, for the COUNT probe ONLY.
+    #
+    # SQL Server rejects an ORDER BY inside a derived table unless TOP/OFFSET/
+    # FETCH legalises it (error 1033), so wrapping "... ORDER BY id" in
+    # SELECT COUNT(*) FROM (...) failed on MSSQL, the best-effort probe returned
+    # nil, and fetch reported the PAGE LENGTH as the total - measured on the lab:
+    # 10 for a 10-row page of 22 matching rows. ORDER BY cannot change a count,
+    # so the probe drops it; the paginated query keeps it. An ORDER BY nested in
+    # a subquery, or one already followed by OFFSET/FETCH/FOR/LIMIT/ROWS, is left
+    # alone. Positions are found on the scrubbed text (same length as the
+    # original), so an "ORDER BY" inside a literal or comment is never cut.
+    # Parity with Python's _strip_trailing_order_by and PHP's
+    # SqlNormalizerTrait::stripTrailingOrderBy.
+    ORDER_BY_RE = /\bORDER\s+BY\b/i.freeze
+    ORDER_TAIL_KEEP_RE = /\b(?:OFFSET|FETCH|FOR|LIMIT|ROWS)\b/i.freeze
+
+    def self.strip_trailing_order_by(sql)
+      return sql if sql.nil? || sql.empty?
+
+      scrubbed = scrub_sql_text(sql)
+      last_top_level = nil
+      scrubbed.to_enum(:scan, ORDER_BY_RE).each do
+        pos = Regexp.last_match.begin(0)
+        last_top_level = pos if top_level_position?(scrubbed, pos)
+      end
+      return sql if last_top_level.nil?
+      return sql if ORDER_TAIL_KEEP_RE.match?(scrubbed[last_top_level..])
+
+      sql[0...last_top_level].rstrip
+    end
+
+    # True when +pos+ sits outside every bracket of the (scrubbed) statement.
+    def self.top_level_position?(scrubbed, pos)
+      scrubbed[0...pos].count("(") == scrubbed[0...pos].count(")")
+    end
+
+    # True when the statement WRITES, even though it may also return rows
+    # (issue #133): INSERT/UPDATE/DELETE ... RETURNING, MSSQL's OUTPUT, MERGE,
+    # or a Postgres data-modifying CTE (WITH x AS (INSERT ...) SELECT ...).
+    #
+    # THE CROSS-FRAMEWORK CONTRACT (identical in Python, PHP, Node and Ruby):
+    # after string literals, quoted identifiers and comments are scrubbed and
+    # leading whitespace/brackets stripped, the statement is a write when its
+    # FIRST WORD is one of WRITE_VERBS, or when it starts with WITH and its body
+    # holds INSERT, UPDATE, DELETE or MERGE. `WHERE note = 'DELETE'` stays a
+    # read because the literal is scrubbed first; a locking read
+    # (`SELECT ... FOR UPDATE`) starts with SELECT and stays a read. Erring
+    # towards "write" is the safe direction: a misread read is merely committed.
+    #
+    # #fetch / #fetch_one run a write exactly once, as written - no COUNT probe,
+    # no pagination, never cached - and commit it like #execute outside an
+    # explicit transaction, so the caller is never handed the id of a row that
+    # does not persist.
+    WRITE_VERBS = %w[INSERT UPDATE DELETE MERGE UPSERT REPLACE].freeze
+    CTE_WRITE_RE = /\b(INSERT|UPDATE|DELETE|MERGE)\b/i.freeze
+
+    def self.write_statement?(sql)
+      scrubbed = scrub_sql_text(sql.to_s).sub(/\A[\s(]+/, "")
+      verb = scrubbed[/\A[A-Za-z]+/].to_s.upcase
+      return true if WRITE_VERBS.include?(verb)
+
+      verb == "WITH" && CTE_WRITE_RE.match?(scrubbed)
+    end
+
+    # True when the statement produces rows (the #execute contract): after
+    # literals and comments are scrubbed, it starts with SELECT, WITH, VALUES,
+    # CALL, EXEC or EXECUTE, or it is a write (.write_statement?) carrying
+    # RETURNING or MSSQL's OUTPUT. A data-modifying CTE starts with WITH, so it
+    # is included. SELECT ... INTO (a table-creating write) is a known edge: it
+    # returns an empty row set.
+    ROW_LEAD_VERBS = %w[SELECT WITH VALUES CALL EXEC EXECUTE].freeze
+    RETURNING_CLAUSE_RE = /\b(?:RETURNING|OUTPUT)\b/i.freeze
+
+    def self.returns_rows?(sql)
+      scrubbed = scrub_sql_text(sql.to_s).sub(/\A[\s(]+/, "")
+      verb = scrubbed[/\A[A-Za-z]+/].to_s.upcase
+      return true if ROW_LEAD_VERBS.include?(verb)
+
+      write_statement?(sql) && RETURNING_CLAUSE_RE.match?(scrubbed)
+    end
+
     # Static factory — cross-framework consistency: Database.create(url)
     def self.create(url, username: "", password: "", pool: nil)
       new(url, username: username.empty? ? nil : username,
@@ -317,6 +426,7 @@ 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}"
+      @operation_driver_key = :"tina4_operation_adapter_#{object_id}"
       # 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,
@@ -453,13 +563,15 @@ module Tina4
     def current_driver
       pinned = Thread.current[@tx_pin_key]
       return pinned if pinned
+      active = Thread.current[@operation_driver_key]
+      return active if active
 
       # 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
+        @pool.peek
       else
         @driver
       end
@@ -582,6 +694,11 @@ module Tina4
       # subqueries downstream survive a user-supplied semicolon.
       sql = Tina4::Database.strip_trailing_semicolons(sql)
 
+      # Issue #133: a write that returns rows is a WRITE - run it once, as
+      # written (no pagination, no count probe, no cache), and commit it like
+      # #execute outside an explicit transaction.
+      return fetch_write(drv, sql, params) if Tina4::Database.write_statement?(sql)
+
       effective_sql = sql
       # Skip appending LIMIT if the statement already ENDS with its own.
       #
@@ -656,6 +773,10 @@ module Tina4
     # never populated either. Default `false` preserves cached behaviour.
     def fetch_one(sql, params = [], no_cache: false)
       sql = Tina4::Database.strip_trailing_semicolons(sql)
+      # Issue #133: INSERT/UPDATE/DELETE ... RETURNING through fetch_one is a
+      # write - commit it like #execute (never cached), see .write_statement?.
+      return fetch_write(current_driver, sql, params).records.first if Tina4::Database.write_statement?(sql)
+
       if @cache_enabled && !no_cache
         key = cache_key(sql + ":ONE", params)
         cached = cache_get(key)
@@ -674,7 +795,25 @@ module Tina4
       fetch_one_direct(sql, params)
     end
 
+    # tina4: ADR-0069 - a data or filter-map KEY becomes a bare column name in
+    # the SQL these helpers build, so it must be a plain identifier (letters,
+    # digits, underscore, dollar; not starting with a digit). Anything else is
+    # refused before any SQL. Valid names are emitted exactly as before.
+    PLAIN_COLUMN_NAME = /\A[A-Za-z_][A-Za-z0-9_$]*\z/.freeze
+
+    def check_column_names!(keys)
+      keys.each do |key|
+        raise ArgumentError, "Invalid column name '#{key}'" unless key.to_s.match?(PLAIN_COLUMN_NAME)
+      end
+    end
+    private :check_column_names!
+
     def insert(table, data)
+      if data.is_a?(Array)
+        data.each { |row| check_column_names!(row.keys) }
+      else
+        check_column_names!(data.keys)
+      end
       cache_invalidate if @cache_enabled
       drv = current_driver
 
@@ -765,6 +904,7 @@ module Tina4
       if filter.is_a?(Hash)
         return ["", []] if filter.empty?
 
+        check_column_names!(filter.keys)
         drv = current_driver
         [filter.keys.map { |k| "#{k} = #{drv.placeholder}" }.join(" AND "), filter.values]
       else
@@ -779,6 +919,7 @@ module Tina4
     # 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)
+      check_column_names!(data.keys)
       where_sql, where_params = as_where(filter, params)
       data = data.dup
 
@@ -850,8 +991,9 @@ module Tina4
 
     # Delete rows. A filterless delete raises; use truncate() to empty a table.
     def delete(table, filter = {}, params = nil)
-      # List of hashes — delete each row
+      # List of hashes — delete each row (every key checked before the first delete)
       if filter.is_a?(Array)
+        filter.each { |row| check_column_names!(row.keys) if row.is_a?(Hash) }
         total = 0
         filter.each { |row| total += delete(table, row).affected_rows }
         return Tina4::DatabaseResult.new([], affected_rows: total, last_id: nil)
@@ -914,8 +1056,14 @@ module Tina4
     # 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.
+    # ROWS: a statement that produces rows - SELECT, WITH ... SELECT, a write
+    # with RETURNING (MSSQL: OUTPUT), CALL/EXEC - returns a Tina4::DatabaseResult
+    # carrying them, the SAME type #fetch returns (cross-framework contract,
+    # matching PHP). It runs exactly once, as written: no COUNT probe, no
+    # LIMIT/OFFSET. A write among them commits like any other write outside an
+    # explicit transaction. This used to hand back the DRIVER's raw result (a
+    # PG::Result, a Mysql2 result, an Fb::Cursor), and `true` for WITH and
+    # OUTPUT. A write that returns no rows still returns 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
@@ -924,14 +1072,15 @@ module Tina4
     def execute(sql, params = [])
       cache_invalidate if @cache_enabled
       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 ")
+      if Tina4::Database.returns_rows?(sql)
+        result = fetch_direct(drv, Tina4::Database.strip_trailing_semicolons(sql), params)
+        autocommit_standalone_write(drv) if Tina4::Database.write_statement?(sql)
         return result
       end
+
+      drv.execute(sql, params)
+      @last_error = nil
+      autocommit_standalone_write(drv)
       true
     rescue => e
       @last_error = e.message
@@ -1015,18 +1164,12 @@ module Tina4
     end
 
     def transaction
-      drv = current_driver
-      Thread.current[@tx_pin_key] = drv
-      Thread.current[@tx_depth_key] = 1
-      drv.begin_transaction
+      start_transaction
       yield self
-      drv.commit
+      commit
     rescue => e
-      drv.rollback if drv
+      rollback if Thread.current[@tx_pin_key]
       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.
@@ -1054,10 +1197,15 @@ module Tina4
         Thread.current[@tx_depth_key] = depth + 1
         return
       end
-      drv = current_driver
+      drv = Thread.current[@operation_driver_key] || (@pool ? @pool.checkout : current_driver)
       Thread.current[@tx_pin_key] = drv
       Thread.current[@tx_depth_key] = 1
-      drv.begin_transaction
+      begin
+        drv.begin_transaction
+      rescue
+        release_transaction_driver(discard: true)
+        raise
+      end
     end
 
     # Commit the current transaction and release the driver pin.
@@ -1078,9 +1226,8 @@ module Tina4
       end
       current_driver.commit
       @last_error = nil
-      # Success — release the pin.
-      Thread.current[@tx_pin_key] = nil
-      Thread.current[@tx_depth_key] = nil
+      # Success — release the exclusive transaction lease.
+      release_transaction_driver
     rescue => e
       # Keep the pin so rollback reaches this same connection.
       @last_error = e.message
@@ -1095,14 +1242,15 @@ module Tina4
     # 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
+      failed = false
       current_driver.rollback
       @last_error = nil
     rescue => e
+      failed = true
       @last_error = e.message
       raise
     ensure
-      Thread.current[@tx_pin_key] = nil
-      Thread.current[@tx_depth_key] = nil
+      release_transaction_driver(discard: failed)
     end
 
     def tables
@@ -1168,12 +1316,14 @@ module Tina4
 
     # Check out a driver from the pool (or return the single driver).
     def checkout
-      current_driver
+      @pool ? @pool.checkout : current_driver
     end
 
-    # Return a driver to the pool. No-op for round-robin pool or single connection.
-    def checkin(_driver)
-      # no-op
+    # Explicit borrowers must return their own lease. Transaction leases are
+    # released only by commit/rollback, never by an unrelated checkin.
+    def checkin(driver)
+      raise ArgumentError, "Cannot check in an active transaction" if driver.equal?(Thread.current[@tx_pin_key])
+      @pool&.checkin(driver)
     end
 
     # Close all pooled connections (or the single connection).
@@ -1256,6 +1406,43 @@ module Tina4
       sequence_next(seq_key, table: table, pk_column: pk_column)
     end
 
+    # Keep the entire public operation (including nested metadata/query calls)
+    # on one lease. A transaction may adopt it and keep it beyond this scope.
+    def with_operation_driver
+      return yield unless @pool
+      return yield if Thread.current[@tx_pin_key] || Thread.current[@operation_driver_key]
+      driver = @pool.checkout
+      Thread.current[@operation_driver_key] = driver
+      discard = false
+      begin
+        yield
+      rescue
+        # A failed standalone PostgreSQL statement may leave an aborted
+        # transaction. Reset it before another caller can borrow the driver.
+        unless Thread.current[@tx_pin_key].equal?(driver)
+          begin
+            driver.rollback
+          rescue
+            discard = true
+          end
+        end
+        raise
+      ensure
+        Thread.current[@operation_driver_key] = nil
+        @pool.checkin(driver, discard: discard) unless Thread.current[@tx_pin_key].equal?(driver)
+      end
+    end
+
+    def release_transaction_driver(discard: false)
+      driver = Thread.current[@tx_pin_key]
+      Thread.current[@tx_pin_key] = nil
+      Thread.current[@tx_depth_key] = nil
+      if @pool && driver && !Thread.current[@operation_driver_key].equal?(driver)
+        @pool.checkin(driver, discard: discard)
+      end
+    end
+    private :with_operation_driver, :release_transaction_driver
+
     private
 
     # Run a fetch straight against the driver — no cache lookup or store.
@@ -1296,7 +1483,8 @@ module Tina4
 
       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)
+      probe_sql = Tina4::Database.strip_trailing_order_by(sql)
+      rows = drv.execute_query("SELECT COUNT(*) AS tina4_total FROM (#{probe_sql}\n)#{suffix}", params)
       row = rows.is_a?(Array) ? rows.first : nil
       return nil unless row.is_a?(Hash)
 
@@ -1306,6 +1494,24 @@ module Tina4
       nil
     end
 
+    # Issue #133: run a write that returns rows (INSERT/UPDATE/DELETE ...
+    # RETURNING, MSSQL OUTPUT) reached through #fetch / #fetch_one.
+    #
+    # The Python master ended fetch/fetch_one with a ROLLBACK outside a
+    # transaction, so the caller got the id of a row that was then discarded -
+    # silent data loss. Here the write gets exactly what #execute gives it: the
+    # query cache is invalidated (and never populated), the statement runs once
+    # AS WRITTEN on ONE driver (no LIMIT/OFFSET or COUNT probe wrapped round it),
+    # and autocommit_standalone_write commits it on that same driver unless an
+    # explicit transaction owns the connection - inside start_transaction the
+    # caller's commit/rollback still decides.
+    def fetch_write(drv, sql, params)
+      cache_invalidate if @cache_enabled
+      result = fetch_direct(drv, sql, params)
+      autocommit_standalone_write(drv)
+      result
+    end
+
     def fetch_direct(drv, effective_sql, params, limit: 0, offset: 0, total: nil)
       result = drv.execute_query(effective_sql, params)
       @last_error = nil
@@ -1818,4 +2024,14 @@ module Tina4
       raise "Driver #{klass_name} not loaded. Install the required gem."
     end
   end
+  module DatabaseOperationLeases
+    %i[fetch_all fetch fetch_one insert primary_key update delete truncate
+       get_last_id execute tables columns table_exists? get_next_id commit rollback].each do |operation|
+      define_method(operation) do |*args, **kwargs, &block|
+        with_operation_driver { super(*args, **kwargs, &block) }
+      end
+    end
+  end
+  Database.prepend(DatabaseOperationLeases)
+
 end

data/lib/tina4/database_adapter.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # The contract every database driver must satisfy.

data/lib/tina4/database_result.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 
 module Tina4

data/lib/tina4/database_url.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "uri"
 

data/lib/tina4/debug.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 # Backward compatibility: Tina4::Debug is now Tina4::Log
 require_relative "log"

data/lib/tina4/dev.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 # Convenience require for all development/optional tools.
 # Usage: require "tina4/dev"