beagle-turso 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f49be5566a3b64416bccffc8c792e167e770139827016890070836eac6ab2484
-  data.tar.gz: c8be2046fb4e78a337008dcdd488f5b8587d754c77692d73e15f90dc0e3d2f8b
+  metadata.gz: 5e39443726eb8f83cd09daee0845abd245e7cde71e4ccde2517129f3340dd80d
+  data.tar.gz: bf31133bd580a883078fdb07ec997b364965c03136d573d311bb7af2e21204a2
 SHA512:
-  metadata.gz: 591b0e8a2e9e71d767008bac9a2742a2c93e4bb74424f586d2af035339aa1510c6fb883e770b20440a9ad561b5c88e9b113f63f8b4b506355e18f4e39442ee23
-  data.tar.gz: 53782d7a3a82cffb627bdbc107ab022619cae5fe49a7fdc85d233aa04910497da7932de863b384d14199d77f63d35473021bf5adc8d95d5d97c13b00355d3145
+  metadata.gz: 3b1cd258ea7a8945cad36c7a18011bd3477bfc43d7b861d71f6105c23fb7f8dbde2ba1d180cb3cbdf2582ec345555117411f8efa72c6fc3acd522953ea7807e7
+  data.tar.gz: 0272a225ec262995350a0a9e5d8dff4aba8f2d49bf0ecf911363919fe4f64e7d5d1956a28c550bd32e5a339309ba30148ce533df3722b30e96c9aa21ccad76d3

data/README.md

@@ -125,8 +125,26 @@ still a `RuntimeError`. A replica file already held by another process raises
 - One `Database` may be shared by threads. Give each thread its own
   `Connection`; a shared `Connection` works but serializes its callers.
 - `open`, `connect`, `push` and `pull` release the GVL, so other threads keep
-  running while they wait on the network. Queries keep it; they are local and
-  fast.
+  running while they wait on the network.
+- Statements (`execute`, `query`, `query_result`, `query_result_with_types`,
+  `execute_batch`) also release the GVL, so a long query or bulk import doesn't
+  stop other threads. Statements on one database file still run one at a
+  time, as they did under the GVL. That covers every connection of every
+  `Database` the process opened on that file, such as one per connection in
+  an ActiveRecord pool. A statement waits for the one in flight, never for a
+  whole transaction or import. Reads wait too: a long `SELECT` holds up every
+  other statement on that file until it finishes. The engine can't run them
+  side by side safely, so put long reports on a dedicated thread or worker.
+- A statement never waits inside the engine for a busy write lock: it raises
+  `BusyError` at once, and `PRAGMA busy_timeout` has no effect. A wait there
+  would block the transaction holding the lock from committing. Retry
+  `BusyError` in your own code, as the Sequel adapter does.
+- To keep statements under the GVL (the 0.3.0 behaviour), set
+  `BEAGLE_TURSO_STATEMENT_GVL=hold` (read once, when the gem loads; any case)
+  or call `Beagle::Turso.statement_gvl = :hold`; `:release` is the default.
+  Any other value of the variable is ignored, with a warning.
+  `Beagle::Turso.statement_gvl` returns the current mode. The setting is
+  process-wide.
 - While one thread pushes, `closed?` returns immediately on other threads, and
   queries on other connections proceed.
 - On a synced database, `connect` called while another thread is pushing waits
@@ -136,14 +154,19 @@ still a `RuntimeError`. A replica file already held by another process raises
   request.
 - `close` during an in-flight `push` is safe: the push finishes or raises, and
   later calls raise `ClosedError`.
-- A blocked native call cannot be interrupted: `Timeout` and `Thread#kill`
-  take effect when it returns.
+- A statement still waiting for another on the same file stops at once for
+  `Timeout`, `Thread#raise` or `Thread#kill`; it has not run. Once a statement
+  has started, it cannot be interrupted, and neither can `open`, `connect`,
+  `push` or `pull`: `Timeout` and `Thread#kill` take effect when the call
+  returns.
 - **Falcon / Async:** on Ruby 4.0+ with `async` 2.25+ (enable its worker pool
   with `ASYNC_SCHEDULER_WORKER_POOL=true` or
   `Async::Scheduler.new(worker_pool: true)`), a fiber scheduler runs these
-  calls on a worker thread, so the reactor keeps serving other requests during
-  a sync. On Ruby 3.3/3.4 the GVL is still released, but the scheduler's own
-  thread blocks. Run sync from a dedicated thread there. Run one Falcon
+  calls and statements on a worker thread, so the reactor keeps serving other
+  requests during a sync or a long statement. A fiber's query waits (off the
+  reactor) for any statement in flight on the same file. On Ruby 3.3/3.4
+  the GVL is still released, but nothing is offloaded: the scheduler's own
+  thread blocks. Run sync and long imports from a dedicated thread there. Run one Falcon
   process per replica (`--count 1`): the replica file is locked to one
   process.
 - **Fork:** handles are bound to the process that opened them. In a forked
@@ -218,6 +241,20 @@ db.close
   (each worker gets its own) and call `stop` from `on_worker_shutdown` or
   `at_exit`.
 
+## Known engine issue: self-referencing foreign keys
+
+Turso's engine has open bugs with foreign keys that reference their own table
+(such as `parent_id`): a multi-row `DELETE`, `UPDATE` or `DROP` that SQLite accepts can fail with
+`FOREIGN KEY constraint failed`, and `ON DELETE SET NULL` / `CASCADE` can leave
+rows behind or orphaned
+([tursodatabase/turso#8713](https://github.com/tursodatabase/turso/issues/8713),
+[#9279](https://github.com/tursodatabase/turso/issues/9279),
+[#9293](https://github.com/tursodatabase/turso/issues/9293),
+[#9294](https://github.com/tursodatabase/turso/issues/9294)). Foreign keys
+between two different tables are unaffected. Workaround: avoid `ON DELETE`
+actions on self-referencing foreign keys, and delete children before parents,
+one level at a time.
+
 ## Credential safety
 
 `auth_token` is never included in `inspect` output or in error messages —

data/ext/beagle_turso/Cargo.toml

@@ -9,5 +9,5 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8", features = ["rb-sys"] }
-beagle_turso_core = "0.2.0"
+beagle_turso_core = "0.3.0"
 rb-sys = "0.9"

data/ext/beagle_turso/src/errors.rs

@@ -23,6 +23,9 @@ pub fn raise_core(ruby: &Ruby, e: CoreError) -> Error {
         CoreError::Busy(_) => "BusyError",
         CoreError::Closed => "ClosedError",
         CoreError::Forked { .. } => "ForkedError",
+        // Never raised: run_statement retries an interrupted wait, or Ruby
+        // raises its pending interrupt instead. The base class, to be safe.
+        CoreError::Interrupted => "Error",
         // Value conversion problems stay Ruby's TypeError, as in 0.1.x.
         CoreError::Type(_) => return Error::new(ruby.exception_type_error(), e.to_string()),
     };

data/ext/beagle_turso/src/lib.rs

@@ -14,22 +14,71 @@
 // identical; the code is simpler and compiles with zero deprecation
 // warnings.
 
-// GVL: open_local, open, connect, push and pull (the calls that can wait on the
-// network or disk for a long time) run via nogvl::without_gvl with the GVL
-// released. Queries/execute stay under the GVL: they are short, local, and
-// release/reacquire would cost more than it saves.
+// GVL: open_local, open, connect, push and pull, and the five statement
+// methods (execute, query, query_result, query_result_with_types,
+// execute_batch) run via nogvl::without_gvl with the GVL released, so other
+// threads run and a worker-pool fiber scheduler offloads them off its reactor.
+// Statement params are converted to core values before the call and Ruby rows
+// built after it; the closure touches no Ruby object. The core serialises
+// statements per database file (its statement lock, shared by every Database
+// in the process opened on that file), so releasing the GVL adds no new write
+// overlap. `Beagle::Turso.statement_gvl = :hold` (or
+// BEAGLE_TURSO_STATEMENT_GVL=hold at load) runs statements under the GVL
+// instead, as in 0.3.0. last_insert_rowid, close and closed? stay under the
+// GVL: they are cheap.
 
 mod errors;
 mod nogvl;
 
-use beagle_turso_core::{Connection, Database, OpenOptions, Value};
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use beagle_turso_core::{Connection, Database, Error as CoreError, OpenOptions, Value};
 use errors::raise_core;
-use nogvl::without_gvl;
+use nogvl::{without_gvl, without_gvl_interruptible};
 use magnus::{
     encoding::EncodingCapable, function, method, prelude::*, Error, Float, Integer, IntoValue,
     RArray, RString, Ruby,
 };
 
+// Process-wide: true runs statements with the GVL held (`statement_gvl :hold`).
+static HOLD_STATEMENT_GVL: AtomicBool = AtomicBool::new(false);
+
+fn set_statement_gvl_hold(hold: bool) {
+    HOLD_STATEMENT_GVL.store(hold, Ordering::Relaxed);
+}
+
+fn statement_gvl_hold() -> bool {
+    HOLD_STATEMENT_GVL.load(Ordering::Relaxed)
+}
+
+// Never set: the interrupt flag for statements run under the GVL.
+static NEVER_INTERRUPTED: AtomicBool = AtomicBool::new(false);
+
+// Runs one statement: without the GVL by default, or directly under it when
+// the switch is `:hold`. `f` must touch no Ruby object; it returns the core
+// Result, which the caller maps to a Ruby exception once the GVL is back.
+//
+// Without the GVL, `f` gets the flag Ruby's unblocking function sets, so
+// Thread#raise/kill and Timeout stop a statement still waiting for another on
+// the same file (the core returns Interrupted; one already running finishes).
+// Ruby then raises its pending exception from without_gvl_interruptible. If it
+// has none to raise (a trap handler ran, say), the statement waits again.
+fn run_statement<F, R>(mut f: F) -> Result<Result<R, CoreError>, Error>
+where
+    F: FnMut(&AtomicBool) -> Result<R, CoreError> + Send,
+    R: Send,
+{
+    if statement_gvl_hold() {
+        return Ok(f(&NEVER_INTERRUPTED));
+    }
+    loop {
+        match without_gvl_interruptible(|flag| f(flag))? {
+            Err(CoreError::Interrupted) => continue,
+            done => return Ok(done),
+        }
+    }
+}
+
 #[magnus::wrap(class = "Beagle::Turso::Database", free_immediately)]
 struct RbDatabase {
     inner: Database,
@@ -166,17 +215,15 @@ fn rows_to_ruby(ruby: &Ruby, rows: Vec<beagle_turso_core::Row>) -> Result<RArray
 impl RbConnection {
     fn execute(ruby: &Ruby, rb_self: &Self, sql: String, params: RArray) -> Result<u64, Error> {
         let p = ruby_array_to_params(ruby, params)?;
-        rb_self
-            .inner
-            .execute(&sql, &p)
+        let inner = &rb_self.inner;
+        run_statement(|i| inner.execute_interruptible(&sql, &p, i))?
             .map_err(|e| raise_core(ruby, e))
     }
 
     fn query(ruby: &Ruby, rb_self: &Self, sql: String, params: RArray) -> Result<RArray, Error> {
         let p = ruby_array_to_params(ruby, params)?;
-        let rows = rb_self
-            .inner
-            .query(&sql, &p)
+        let inner = &rb_self.inner;
+        let rows = run_statement(|i| inner.query_result_interruptible(&sql, &p, i).map(|r| r.rows))?
             .map_err(|e| raise_core(ruby, e))?;
         rows_to_ruby(ruby, rows)
     }
@@ -192,10 +239,10 @@ impl RbConnection {
         params: RArray,
     ) -> Result<RArray, Error> {
         let p = ruby_array_to_params(ruby, params)?;
-        let result = rb_self
-            .inner
-            .query_result(&sql, &p)
-            .map_err(|e| raise_core(ruby, e))?;
+        let inner = &rb_self.inner;
+        let result =
+            run_statement(|i| inner.query_result_interruptible(&sql, &p, i))?
+                .map_err(|e| raise_core(ruby, e))?;
         let columns = ruby.ary_new();
         for name in &result.columns {
             columns.push(name.clone().into_value_with(ruby))?;
@@ -217,10 +264,10 @@ impl RbConnection {
         params: RArray,
     ) -> Result<RArray, Error> {
         let p = ruby_array_to_params(ruby, params)?;
-        let result = rb_self
-            .inner
-            .query_result(&sql, &p)
-            .map_err(|e| raise_core(ruby, e))?;
+        let inner = &rb_self.inner;
+        let result =
+            run_statement(|i| inner.query_result_interruptible(&sql, &p, i))?
+                .map_err(|e| raise_core(ruby, e))?;
         let columns = ruby.ary_new();
         for name in result.columns {
             columns.push(name)?;
@@ -244,9 +291,8 @@ impl RbConnection {
     }
 
     fn execute_batch(ruby: &Ruby, rb_self: &Self, sql: String) -> Result<(), Error> {
-        rb_self
-            .inner
-            .execute_batch(&sql)
+        let inner = &rb_self.inner;
+        run_statement(|i| inner.execute_batch_interruptible(&sql, i))?
             .map_err(|e| raise_core(ruby, e))
     }
 
@@ -265,6 +311,12 @@ impl RbConnection {
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let turso = ruby.define_module("Beagle")?.define_module("Turso")?;
+    // Back Beagle::Turso.statement_gvl / statement_gvl= (lib/beagle/turso.rb).
+    turso.define_module_function(
+        "_set_statement_gvl_hold",
+        function!(set_statement_gvl_hold, 1),
+    )?;
+    turso.define_module_function("_statement_gvl_hold?", function!(statement_gvl_hold, 0))?;
     let db = turso.define_class("Database", ruby.class_object())?;
     db.define_singleton_method("open_local", function!(RbDatabase::open_local, 1))?;
     // Positional primitive; the public keyword-arg `Database.open` wrapper

data/ext/beagle_turso/src/nogvl.rs

@@ -3,16 +3,20 @@
 // move the call to a worker thread (keeping its reactor live).
 //
 // The closure must not touch any Ruby object: convert arguments before calling
-// and build Ruby results after it returns. No unblocking function is passed,
-// so Thread#raise/kill (and Timeout) are delivered only once the call returns:
-// rb_nogvl then raises the pending interrupt by longjmp. That is caught with
-// rb_protect (magnus::rb_sys::protect), so it never unwinds through Rust
-// frames; any value the native call produced is dropped normally (for `open`,
-// the Database is closed) and the exception comes back as `Err`.
+// and build Ruby results after it returns. `without_gvl` passes no unblocking
+// function, so Thread#raise/kill (and Timeout) are delivered only once the
+// call returns. `without_gvl_interruptible` passes one that sets a flag the
+// closure can watch, so it can stop *waiting* early; work it has begun still
+// runs to the end. Either way, rb_nogvl then raises the pending interrupt by
+// longjmp. That is caught with rb_protect (magnus::rb_sys::protect), so it
+// never unwinds through Rust frames; any value the native call produced is
+// dropped normally (for `open`, the Database is closed) and the exception
+// comes back as `Err`.
 
 use std::ffi::c_void;
 use std::panic::{self, AssertUnwindSafe};
 use std::ptr;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 use magnus::Error;
 
@@ -36,19 +40,50 @@ where
     ptr::null_mut()
 }
 
+// The unblocking function: Ruby calls it, holding the GVL, from the thread that
+// wants to interrupt this one. It only sets the flag.
+unsafe extern "C" fn set_flag(data: *mut c_void) {
+    (*(data as *const AtomicBool)).store(true, Ordering::Release);
+}
+
 pub fn without_gvl<F, R>(f: F) -> Result<R, Error>
+where
+    F: FnOnce() -> R + Send,
+    R: Send,
+{
+    call_without_gvl(f, None)
+}
+
+pub fn without_gvl_interruptible<F, R>(f: F) -> Result<R, Error>
+where
+    F: FnOnce(&AtomicBool) -> R + Send,
+    R: Send,
+{
+    let flag = AtomicBool::new(false);
+    let flag = &flag;
+    call_without_gvl(move || f(flag), Some(flag))
+}
+
+fn call_without_gvl<F, R>(f: F, interrupt: Option<&AtomicBool>) -> Result<R, Error>
 where
     F: FnOnce() -> R + Send,
     R: Send,
 {
     let mut call = Call { f: Some(f), out: None };
+    let (ubf, ubf_data) = match interrupt {
+        Some(flag) => (
+            Some(set_flag as unsafe extern "C" fn(*mut c_void)),
+            flag as *const AtomicBool as *mut c_void,
+        ),
+        None => (None, ptr::null_mut()),
+    };
     let protected = magnus::rb_sys::protect(|| {
         unsafe {
             rb_sys::rb_nogvl(
                 Some(trampoline::<F, R>),
                 &mut call as *mut Call<F, R> as *mut c_void,
-                None,
-                ptr::null_mut(),
+                ubf,
+                ubf_data,
                 RB_NOGVL_OFFLOAD_SAFE,
             );
         }

data/lib/beagle/turso/version.rb

@@ -1,5 +1,5 @@
 module Beagle
   module Turso
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/beagle/turso.rb

@@ -15,6 +15,33 @@ end
 
 module Beagle
   module Turso
+    # Whether statements (Connection#execute, #query, #query_result,
+    # #query_result_with_types, #execute_batch) release the GVL: :release (the
+    # default) lets other threads run and a worker-pool fiber scheduler offload
+    # them; :hold keeps them under the GVL, as in 0.3.0. Process-wide.
+    def self.statement_gvl
+      _statement_gvl_hold? ? :hold : :release
+    end
+
+    def self.statement_gvl=(mode)
+      unless mode == :hold || mode == :release
+        raise ArgumentError, "statement_gvl must be :hold or :release"
+      end
+      _set_statement_gvl_hold(mode == :hold)
+    end
+
+    private_class_method :_statement_gvl_hold?, :_set_statement_gvl_hold
+
+    # Case and surrounding space don't matter. Anything else is most likely a
+    # typo in a rollback attempt, so it is reported rather than ignored.
+    case (env_gvl = ENV["BEAGLE_TURSO_STATEMENT_GVL"].to_s).strip.downcase
+    when "hold" then self.statement_gvl = :hold
+    when "", "release" then nil
+    else
+      warn "beagle-turso: ignoring BEAGLE_TURSO_STATEMENT_GVL=#{env_gvl.inspect} " \
+           "(expected hold or release); statements release the GVL"
+    end
+
     class Database
       # Opens a local-only database, or one synced with a remote Turso
       # database when both `remote_url` and `auth_token` are given (see

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - BeagleSoftwareUK
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys