activerecord-beagle-turso 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd2ebde88afce8658ba27c6a8ae41ffb3228e6ec7bb6c65be6ff0a5a1c56d6ec
-  data.tar.gz: 2c6ac050108dd08d75808fb5aa28854164f91835c6529ff400ff97351d81c449
+  metadata.gz: 85d72dcc7cf48c86d50b2e81ec3d481b0ab33c1aa3a9f1425574a82d3662c94a
+  data.tar.gz: 05c6675f967450f5f0aa66c22e0bf0244da1ed4874645d93265f13e1a0a40a77
 SHA512:
-  metadata.gz: 0cc05e0873fd0a0d143c2bae7758320768b06bdca6f6cd676de504cc09bc61360877aa81fa7d4b88ca7836758103135d3056d15cc5587721481b826fd9d0855c
-  data.tar.gz: d0be294e7c35be6e5275cbbbcb54e80546ddb1b4c30a6f6ea32b72ec88c8554eded57b6537e128581ce599c3d1c173e49c443f7ca4e88ba7366641d351b9916d
+  metadata.gz: '0937eb27407a0acf3ff4ce564181d949dc0578559faba7f76a49b41c0a597b47add6d34881df708cbae16e8629b40dcf6113fbbaed00d7703756da7c2cfca585'
+  data.tar.gz: 719662f8a03bc87f2a8b29f4f9f5d0e7ca48c66323f3b3258a67abd0f833e53a08c4df1a4db5e899a45ad696a261ef2ac4d2bbe3fa6dc5fd73207e4e7f69aa51

data/README.md

@@ -68,7 +68,10 @@ does not cover them automatically. Source them from encrypted credentials or
 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.
-Without `timeout:` (or with 0), a busy write raises at once.
+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
@@ -247,6 +250,17 @@ this gem.
    each sync — pick a sync cadence accordingly, or run Solid Queue in a separate
    process.
 
+4. **One process per database file.** A local Turso database file is locked to
+   the process that opened it (SQLite lets processes share a file; Turso does
+   not), so a second process opening it fails with `OpenError` ("... File is
+   locked by another process") while the first holds a connection. The common
+   case is handled: `bin/rails db:test:prepare test` (or `... spec`) runs the
+   tests in a child process, so when a `db:*` rake task finishes the adapter
+   releases its own file-backed connections in the rake process
+   (`BeagleTurso::TestProcessRelease`). In-memory databases, other adapters'
+   connections and `Beagle::Turso::Database`s opened outside ActiveRecord are
+   left alone.
+
 ## Known engine issue: self-referencing foreign keys
 
 Turso's engine has open bugs with foreign keys that reference their own table

data/lib/active_record/connection_adapters/beagle_turso/migration_push.rb

@@ -2,6 +2,7 @@
 
 require "active_record/connection_adapters/beagle_turso/errors"
 require "active_record/connection_adapters/beagle_turso/sync_manager"
+require "active_record/connection_adapters/beagle_turso/test_process_release"
 
 module ActiveRecord
   module ConnectionAdapters
@@ -199,6 +200,7 @@ module ActiveRecord
           rake_tasks do
             require "rake"
             MigrationPush.install!
+            TestProcessRelease.install!
           end
         end
       end

data/lib/active_record/connection_adapters/beagle_turso/test_process_release.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module BeagleTurso
+      # Lets `bin/rails db:test:prepare test` -- the Rails CI default -- run as
+      # one command (and `db:test:prepare spec`, or any task after it that
+      # starts a process of its own).
+      #
+      # The rake test tasks do not run the tests in the rake process:
+      # Rails::TestUnit::Runner.run_from_rake starts a separate `rails test`
+      # process and waits for it (rspec-rails' `spec` task does the same). A
+      # local Turso database file is locked to the process that opened it --
+      # SQLite lets processes share a file, Turso does not -- and
+      # db:test:prepare left its connection open, so the test process could
+      # not open the database:
+      #
+      #   open failed: Locking error: Failed locking file '.../storage/test.sqlite3'.
+      #   File is locked by another process
+      #
+      # So when an outermost db:* task finishes, this adapter's file-backed
+      # connections in the rake process are released. A pool reconnects on
+      # its next use. In-memory databases are left alone (closing one would
+      # destroy it, and no other process can open it anyway), as are other
+      # adapters' connections.
+      module TestProcessRelease
+        # Prepended onto Rake::Task so it works whatever order the Railtie and
+        # ActiveRecord's own rake tasks load in (same approach as MigrationPush).
+        module TaskHook
+          def execute(args = nil)
+            if name.start_with?("db:")
+              TestProcessRelease.around { super }
+            else
+              super
+            end
+          end
+        end
+
+        class << self
+          def install!
+            return if ::Rake::Task.ancestors.include?(TaskHook)
+            ::Rake::Task.prepend(TaskHook)
+          end
+
+          # Releases once, when the outermost db:* task finishes: a db task
+          # that invokes others (db:test:prepare -> db:test:load_schema) keeps
+          # its connection until it is done.
+          def around
+            self.depth = depth + 1
+            yield
+          ensure
+            self.depth = depth - 1
+            release_connections! if depth.zero?
+          end
+
+          def release_connections!
+            # Not loaded means nothing connected; don't load it to find out.
+            return unless defined?(::ActiveRecord::Base) && !::ActiveRecord.autoload?(:Base)
+
+            ::ActiveRecord::Base.connection_handler.connection_pool_list(:all).each do |pool|
+              pool.disconnect! if releasable?(pool.db_config)
+            end
+          end
+
+          def releasable?(db_config)
+            db_config.adapter.to_s == "beagle_turso" && db_config.database.to_s != ":memory:"
+          end
+
+          def depth = Thread.current[:beagle_turso_test_process_release_depth].to_i
+          def depth=(value)
+            Thread.current[:beagle_turso_test_process_release_depth] = value
+          end
+        end
+      end
+    end
+  end
+end

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
@@ -187,31 +257,14 @@ module ActiveRecord
         # 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 = milliseconds.to_i.positive? ? milliseconds.to_i / 1000.0 : nil
+          @busy_timeout = BeagleTursoAdapter.busy_timeout(milliseconds)
         end
 
-        # Retries a statement that lost the single-writer race, with capped
-        # exponential backoff, for up to the busy timeout. 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 the writer holding the lock can finish. The
-        # caller decides what is safe to retry (see BeagleTursoAdapter#perform_query).
-        def retry_busy
-          deadline = nil
-          delay = 0.002
-          begin
-            yield
-          rescue ::Beagle::Turso::BusyError => e
-            raise if @busy_timeout.nil? || e.message.include?("snapshot is stale")
-
-            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            deadline ||= now + @busy_timeout
-            raise if now + delay > deadline
-
-            sleep delay
-            delay = [delay * 2, 0.1].min
-            retry
-          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 ---

data/lib/activerecord/beagle_turso/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module BeagleTurso
-    VERSION = "0.1.8"
+    VERSION = "0.1.10"
   end
 end

data/lib/activerecord-beagle-turso.rb

@@ -6,3 +6,4 @@ require "active_record/connection_adapters/beagle_turso/sync_manager"
 require "active_record/connection_adapters/beagle_turso/sync_job"
 require "active_record/connection_adapters/beagle_turso/errors"
 require "active_record/connection_adapters/beagle_turso/migration_push"
+require "active_record/connection_adapters/beagle_turso/test_process_release"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - BeagleSoftwareUK
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -97,6 +97,7 @@ files:
 - lib/active_record/connection_adapters/beagle_turso/migration_push.rb
 - lib/active_record/connection_adapters/beagle_turso/sync_job.rb
 - lib/active_record/connection_adapters/beagle_turso/sync_manager.rb
+- lib/active_record/connection_adapters/beagle_turso/test_process_release.rb
 - lib/active_record/connection_adapters/beagle_turso_adapter.rb
 - lib/activerecord-beagle-turso.rb
 - lib/activerecord/beagle_turso/version.rb