activerecord-beagle-turso 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51cf88616ac49583385f9d993560cc4f5fb53169707dec16c68b3c37f6d60884
-  data.tar.gz: 21732cc614964877aeca0da6e34d066cfcfb2061747ac68f9eb2803abff60d1a
+  metadata.gz: f368e18d7818a9897c2a59309e2850bb44ad977d97513ae210996d2762f138f7
+  data.tar.gz: ffe739174f2998da3bb0bba9de535687dc6143914c123db6df718e9fe2c361df
 SHA512:
-  metadata.gz: fe0832ec4ae1acc466934cb0ed1a0c47f2de5e5d5f86b47091ffbe1c5e8f77c86ee50534808d2cf7dbef318aa526cd0026146ac367d1c3f56275723d8630ccc3
-  data.tar.gz: bf86e7af654df142cd722228c9245bd5456b6cfd9b2de5a43ae9067e018fee5491e17005896eec7f693ef0fc9e8d9bd9ac1d5791033bfff579879562fd69d1b9
+  metadata.gz: '07097b798e8ef32bfad3d84318c9b1101284631a7e8171006c1a1be788e12d89e4dc292a7ef2155fdcc3468a1730046f4629c2c7fb16cb5bbc69b7d27965ed50'
+  data.tar.gz: 61880c51d328741a0cbf7641bb2e9eb12b946db91f4472265870b5e03b22cd4bc2ae07023381185bea42afc5329777ab83d31f0e4bab553267ee783df070d188

data/README.md

@@ -63,6 +63,16 @@ some diagnostics, but these are custom `database.yml` keys, so that masking
 does not cover them automatically. Source them from encrypted credentials or
 `ENV`, as above, and avoid logging/inspecting the raw connection config.
 
+`timeout:` (milliseconds, as in the stock SQLite adapter; Rails' generated
+`database.yml` sets 5000) is how long a write waits for another connection's
+transaction to finish before raising `Beagle::Turso::BusyError`. Transactions
+begin with `BEGIN IMMEDIATE`, so a writer waits at `BEGIN`, never part-way
+through. The wait sleeps in Ruby, so other threads and fibers keep running.
+Opening a new connection waits the same way when a synced replica is busy
+with a sync (the engine reports "database tape error: database is busy" as an
+`OpenError` or `ConnectError`), so a pool growing during a `SyncJob` no
+longer fails. Without `timeout:` (or with 0), both raise at once.
+
 An optional `bootstrap_if_empty:` (default `true`) controls whether a brand
 new/empty local file is populated from the remote on first open — see
 `Beagle::Turso::Database.open`.

data/lib/active_record/connection_adapters/beagle_turso_adapter.rb

@@ -74,12 +74,87 @@ module ActiveRecord
       INSERT_STATEMENT_REGEX = /\A\s*(?:(?:INSERT|REPLACE)\b|WITH\b[\s\S]*\)\s*(?:INSERT|REPLACE)\b)/i
       private_constant :INSERT_STATEMENT_REGEX
 
+      # A statement that lost the single-writer race. A stale snapshot is
+      # never retried: the transaction that read it has to start again.
+      STATEMENT_BUSY = lambda do |error|
+        error.is_a?(::Beagle::Turso::BusyError) && !error.message.include?("snapshot is stale")
+      end
+      private_constant :STATEMENT_BUSY
+
+      # Opening or connecting to a synced replica while another connection
+      # syncs it. The sync engine reports that as "database tape error:
+      # database is busy" inside an OpenError or ConnectError (the driver only
+      # classifies the engine's own "Database is busy" as BusyError).
+      OPEN_BUSY = lambda do |error|
+        STATEMENT_BUSY.call(error) ||
+          ((error.is_a?(::Beagle::Turso::OpenError) || error.is_a?(::Beagle::Turso::ConnectError)) &&
+            error.message.match?(/database is busy/i))
+      end
+      private_constant :OPEN_BUSY
+
       class << self
         # Open a beagle-turso Database (synced remote when +remote_url+ is
         # present, otherwise local/in-memory) and wrap it so the SQLite3Adapter
-        # can drive it as a raw connection.
+        # can drive it as a raw connection. A busy open is retried for
+        # database.yml's `timeout:`, like a busy statement.
         def new_client(config)
-          database =
+          busy = ->(error) { OPEN_BUSY.call(error) || torn_meta_read?(error, config) }
+          retry_busy(busy_timeout(config[:timeout]), busy: busy) do
+            database = open_database(config)
+            begin
+              Client.new(database)
+            rescue Exception
+              database.close
+              raise
+            end
+          end
+        end
+
+        # `timeout:` (ms, as in database.yml) as seconds; nil means no waiting.
+        def busy_timeout(milliseconds)
+          milliseconds.to_i.positive? ? milliseconds.to_i / 1000.0 : nil
+        end
+
+        # Retries the block while it raises an error +busy+ accepts, with
+        # capped exponential backoff, for up to +timeout+ seconds. The engine
+        # never waits for a lock itself (from beagle-turso 0.4.0 it raises at
+        # once), so this is where the wait happens. sleep releases the GVL and
+        # yields to a fiber scheduler, so whoever holds the lock can finish.
+        def retry_busy(timeout, busy:)
+          deadline = nil
+          delay = 0.002
+          begin
+            yield
+          rescue ::Beagle::Turso::Error => e
+            raise if timeout.nil? || !busy.call(e)
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            deadline ||= now + timeout
+            raise if now + delay > deadline
+
+            sleep delay
+            delay = [delay * 2, 0.1].min
+            retry
+          end
+        end
+
+        def synced_config?(config)
+          !config[:remote_url].to_s.empty? && !config[:auth_token].to_s.empty?
+        end
+
+        private
+          # The sync engine (turso 0.8.3) rewrites a replica's metadata file
+          # (`<database>-info`) in place, truncating it first, so an open that
+          # reads it mid-sync can find it empty and fail with "meta must be
+          # initialized before open". Retried only when the file is there: a
+          # replica that was never initialised fails at once.
+          def torn_meta_read?(error, config)
+            error.is_a?(::Beagle::Turso::OpenError) &&
+              error.message.include?("meta must be initialized before open") &&
+              File.exist?("#{config[:database]}-info")
+          end
+
+          def open_database(config)
             if config[:remote_url]
               Beagle::Turso::Database.open(
                 local_path: config[:database].to_s,
@@ -90,12 +165,7 @@ module ActiveRecord
             else
               Beagle::Turso::Database.open_local(config[:database].to_s)
             end
-          Client.new(database)
-        end
-
-        def synced_config?(config)
-          !config[:remote_url].to_s.empty? && !config[:auth_token].to_s.empty?
-        end
+          end
       end
 
       # Adapts a Beagle::Turso::Database + its connected Connection to the subset
@@ -111,9 +181,10 @@ module ActiveRecord
         attr_reader :database, :connection
 
         def initialize(database)
-          @database   = database
-          @connection = database.connect
-          @closed     = false
+          @database     = database
+          @connection   = database.connect
+          @closed       = false
+          @busy_timeout = nil
         end
 
         # A bare read of exactly +defer_foreign_keys+ or +read_uncommitted+
@@ -181,11 +252,22 @@ module ActiveRecord
         def push = database.push
         def pull = database.pull
 
-        # --- sqlite3-gem lifecycle shims the SQLite3Adapter drives ---
-        # configure_connection only touches this when config[:timeout] is set.
-        def busy_handler_timeout=(_)
-          nil
+        # --- busy handling ---
+        # configure_connection passes database.yml's `timeout:` (ms) here, as it
+        # does to the sqlite3 gem's busy handler. Unset or 0 means no waiting:
+        # a BusyError surfaces at once, as with the sqlite3 gem.
+        def busy_handler_timeout=(milliseconds)
+          @busy_timeout = BeagleTursoAdapter.busy_timeout(milliseconds)
         end
+
+        # Retries a statement that lost the single-writer race for up to the
+        # busy timeout (see BeagleTursoAdapter.retry_busy). The caller decides
+        # what is safe to retry (see BeagleTursoAdapter#perform_query).
+        def retry_busy(&)
+          BeagleTursoAdapter.retry_busy(@busy_timeout, busy: STATEMENT_BUSY, &)
+        end
+
+        # --- sqlite3-gem lifecycle shims the SQLite3Adapter drives ---
         # connected? => !(@raw_connection.nil? || @raw_connection.closed?)
         def closed? = @closed
         # Release the beagle-turso session eagerly rather than waiting for GC.
@@ -356,26 +438,10 @@ module ActiveRecord
             if batch
               raw_connection.execute_batch(sql)
               ::ActiveRecord::Result.empty
-            elsif write_statement?(sql)
-              if (rewritten = sql_with_returning_rowid(sql))
-                insert_returning_rowid(raw_connection, rewritten, params)
-              else
-                affected = raw_connection.execute(sql, params)
-                @last_inserted_rowid = raw_connection.last_insert_rowid
-                ::ActiveRecord::Result.empty(affected_rows: affected)
-              end
+            elsif busy_retry?(sql)
+              raw_connection.retry_busy { run_statement(raw_connection, sql, params) }
             else
-              columns, rows = raw_connection.query_result(sql, params)
-              # Belt-and-suspenders: a RETURNING insert lands here (id read from
-              # rows by last_inserted_id), and a data-modifying CTE that slips past
-              # write_statement? would too -- keep the rowid so an inserted id is
-              # never silently lost even on a heuristic miss.
-              if INSERT_REGEX.match?(sql)
-                # On a replica where last_insert_rowid is untrustworthy, never
-                # offer it as a fallback id (a RETURNING insert's id is in rows).
-                @last_inserted_rowid = insert_returning_rowid? ? nil : raw_connection.last_insert_rowid
-              end
-              ::ActiveRecord::Result.new(columns, rows)
+              run_statement(raw_connection, sql, params)
             end
 
           verified!
@@ -384,6 +450,43 @@ module ActiveRecord
           result
         end
 
+        # A busy statement is retried only when that is safe: the BEGIN that
+        # opens a transaction (Rails sends BEGIN IMMEDIATE, so a writer waits
+        # for the lock there rather than failing mid-way), or a statement
+        # outside any transaction. Inside one, a BusyError means the
+        # transaction is dead; it must surface and roll back. A multi-statement
+        # batch is never retried (it may have run in part).
+        BEGIN_REGEX = /\A\s*BEGIN\b/i
+        private_constant :BEGIN_REGEX
+
+        def busy_retry?(sql)
+          !transaction_open? || BEGIN_REGEX.match?(mask_non_code(sql))
+        end
+
+        def run_statement(raw_connection, sql, params)
+          if write_statement?(sql)
+            if (rewritten = sql_with_returning_rowid(sql))
+              insert_returning_rowid(raw_connection, rewritten, params)
+            else
+              affected = raw_connection.execute(sql, params)
+              @last_inserted_rowid = raw_connection.last_insert_rowid
+              ::ActiveRecord::Result.empty(affected_rows: affected)
+            end
+          else
+            columns, rows = raw_connection.query_result(sql, params)
+            # Belt-and-suspenders: a RETURNING insert lands here (id read from
+            # rows by last_inserted_id), and a data-modifying CTE that slips past
+            # write_statement? would too -- keep the rowid so an inserted id is
+            # never silently lost even on a heuristic miss.
+            if INSERT_REGEX.match?(sql)
+              # On a replica where last_insert_rowid is untrustworthy, never
+              # offer it as a fallback id (a RETURNING insert's id is in rows).
+              @last_inserted_rowid = insert_returning_rowid? ? nil : raw_connection.last_insert_rowid
+            end
+            ::ActiveRecord::Result.new(columns, rows)
+          end
+        end
+
         # Route to the WRITE branch (execute -> affected count + last_insert_rowid)
         # rather than the read branch. A statement is a write when SQLite3's own
         # read/write classifier says so, OR when it is a data-modifying CTE that

data/lib/activerecord/beagle_turso/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module BeagleTurso
-    VERSION = "0.1.7"
+    VERSION = "0.1.9"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - BeagleSoftwareUK
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement