beagle-turso 0.1.2-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad135705b9ec7bad8632db4f2d9e690cdad034137497d9aad26e63dd182c08a4
-  data.tar.gz: 4ca85c44ff191c3770c1ed6a74af3a0d66a0b0aa30aa806096f5a6d516d3fcf1
+  metadata.gz: 74f1d9beadf880cf80dc6f87f86fca245cbb9fb079948a02bd06fd7678655d08
+  data.tar.gz: 4bfdf6b3a4df383494f4deeb2df0acbfbf1f72053e8fe5ca72ec3cf4a6daab31
 SHA512:
-  metadata.gz: be6631190c66b8f5772c5e9e3108a7fc7c890caa3d3c4fbc23daa18a4fb43c09e812bf1af6a5ed016de7f88bf112d5ad511d391aecc22d3cc0998c53b299efc6
-  data.tar.gz: 1747c9828a7bb4e06278502414debb4ccd02fe1e2312f9c229898daabd1a421b52ba3e2b318a00514e5ccadd1f85847806bf5e3cb9f136412167cb814035c726
+  metadata.gz: e02e2aeaa8b306412f3f0a3b9ac6513906268bd5832cccf64a0e607e7615329f41cad314e9e8f3de611b4e194cd06a8a5895a3291d8c8b83fd4136bb94f9222c
+  data.tar.gz: ee9b8f7141a2aa0519c499bf220c560460565ac16a1de9c126ec6e64972a21eb957a9836750fae54cff520725a1fa51b54131366138bd3ff00698549987b3912

data/README.md

@@ -68,7 +68,8 @@ db.pull # pull remote changes down to the local file (returns true/false)
 `Database.open` also accepts `bootstrap_if_empty:` (defaults to `true`),
 which pulls all remote data down on first open if the local file is new/empty.
 Calling `push`/`pull` on a database opened via `open_local` (or via `open`
-without both `remote_url:` and `auth_token:`) raises `RuntimeError`.
+without both `remote_url:` and `auth_token:`) raises
+`Beagle::Turso::NotSyncedError`.
 
 ### Durability note: writes commit on-sync, not synchronously
 
@@ -79,6 +80,78 @@ called; `push` is not called automatically after every write. Until a
 `push` succeeds, a write that's durable locally is not yet visible to other
 replicas of the same remote database.
 
+## Which Turso database?
+
+Point a synced database at a Turso database **dedicated to this engine** —
+ideally a fresh, empty one. On first open of an empty local replica,
+`bootstrap_if_empty` pulls the remote down; against a fresh remote that's a
+clean start, and the engine then manages its own state in that database (it
+creates `turso_cdc`, `__turso_internal_*`, and `turso_sync_last_change_id`
+tables and takes an **exclusive lock** on the local replica file — only one
+OS process may hold a given replica open at a time).
+
+Two things to avoid:
+
+- **Don't co-host a synced database with the legacy libSQL/Hrana driver.**
+  This engine (Turso's newer Rust core) and the classic libSQL client have
+  different write/sync models; running both against the same remote database
+  at once risks corrupting its sync state. Give this engine its own database.
+- **Migrating an existing, populated libSQL database into the synced engine
+  is not validated.** A fresh database is the supported, tested path. If you
+  must adopt existing data, treat it as unproven — test push/pull round-trips
+  before relying on it.
+
+A single remote database, dedicated to this engine and written by one process
+at a time, is the model it's built for.
+
+## Errors
+
+Every error the driver raises is a `Beagle::Turso::Error`, a `RuntimeError`
+subclass: `OpenError`, `ConnectError`, `QueryError`, `SyncError`,
+`NotSyncedError` (push/pull on a local-only database), `BusyError` (another
+session or process holds the database), `ClosedError` and `ForkedError`. An
+unsupported bind parameter type raises Ruby's `TypeError`. Auth, network and
+protocol failures during sync all arrive as `SyncError` (or `OpenError` at
+open): the engine does not distinguish them. Messages never contain the auth
+token.
+
+Busy conditions now raise `BusyError` with a message beginning
+`database is busy:` (0.1.x said `query failed:` / `sync failed:`); it is
+still a `RuntimeError`. A replica file already held by another process raises
+`OpenError` ("... File is locked by another process").
+
+## Threads, fibers and fork
+
+- 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.
+- 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
+  inside the engine until the push finishes (about the push's duration); the
+  GVL is released while it waits, so other threads and fibers keep running.
+  Open connections up front (e.g. at boot / pool warm-up) rather than per
+  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.
+- **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
+  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
+  child, `open`, `connect`, `push`, `pull` and queries on an inherited handle
+  raise `ForkedError`; open a new database there. `close` is a no-op and
+  `closed?` is safe (it reports the handle as closed if it can't be inspected),
+  so inherited handles need no cleanup in the child.
+
 ## Credential safety
 
 `auth_token` is never included in `inspect` output or in error messages —

data/lib/beagle/turso/errors.rb

@@ -0,0 +1,19 @@
+module Beagle
+  module Turso
+    # Base class for every error the native driver raises. A RuntimeError so
+    # code written against 0.1.x, which raised bare RuntimeErrors, still rescues.
+    class Error < RuntimeError; end
+
+    class OpenError < Error; end
+    class ConnectError < Error; end
+    class QueryError < Error; end
+    class SyncError < Error; end
+    # push/pull on a database opened without remote_url:/auth_token:.
+    class NotSyncedError < Error; end
+    # The engine reported the database busy (another session or process holds it).
+    class BusyError < Error; end
+    class ClosedError < Error; end
+    # A handle opened in a parent process was used after fork; open a new one.
+    class ForkedError < Error; end
+  end
+end

data/lib/beagle/turso/version.rb

@@ -1,5 +1,5 @@
 module Beagle
   module Turso
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/beagle/turso.rb

@@ -1,4 +1,5 @@
 require_relative "turso/version"
+require_relative "turso/errors"
 
 # Load the native extension. Precompiled ("fat") gems ship the .so under a
 # per-Ruby-ABI subdir (lib/beagle_turso/<major.minor>/beagle_turso.so); a

data/lib/beagle_turso/3.3/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/3.3/beagle_turso.so
-size: 33949400 bytes
-sha256: c2c00504bb57f2d804a334e5a166e3e2022def0173bcdc0b6cfdfd2679351c9f
+size: 36921384 bytes
+sha256: 3c379ba925a07c255667fc8e7c9a302b7f673b2e7e3df555714d6012952854e9

data/lib/beagle_turso/3.4/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/3.4/beagle_turso.so
-size: 33948312 bytes
-sha256: ea28949f1124faf73ee46302afc1098e252eb7642a41bee5f43fbe1170ac542c
+size: 36936560 bytes
+sha256: e895dfcd90349655853f6578437ca109a18fb6f5154b6cfdac5cf3f3d9c5e822

data/lib/beagle_turso/4.0/beagle_turso.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/beagle_turso/4.0/beagle_turso.so
-size: 33944104 bytes
-sha256: dad706a00ee3653b2d742a016b722c8b67dafc39ca5255a428d7af27bbf7aabe
+size: 36936552 bytes
+sha256: 9e83259ad535e81fdb327cf808b00d7449da653bcd35a4a1c92d34a585774934

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: aarch64-linux
 authors:
 - BeagleSoftwareUK
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies: []
 description: |
   A Ruby driver for Turso's database engine, backed by a native Rust
@@ -24,6 +24,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/beagle/turso.rb
+- lib/beagle/turso/errors.rb
 - lib/beagle/turso/version.rb
 - lib/beagle_turso/3.3/beagle_turso.so
 - lib/beagle_turso/3.4/beagle_turso.so