beagle-turso 0.1.2-x86_64-linux → 0.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d56ea88bf691a9947919b8a865b14e960692b2381225a4e75fb4083be2a9e75a
-  data.tar.gz: 9679039fe4536f780c57a61388c4a75cc0e236b0522d74c3688f861361588e3c
+  metadata.gz: c9a414905622147215ada0d6468ba75ea3ccc1c7ad1161011356bed522d1cb47
+  data.tar.gz: 3907e2eeff8f6e946fabf5fc51bfa2320c2dc8afebbde9ae0a25dcbb2c04a83a
 SHA512:
-  metadata.gz: edce357863a3860a808e41a30d5ef5a1cfc91069a766d08f5d00029da871dc32e4763518e38ef034229de9f4247ca67cba9f37074e6b3b4f9b364b2c0f7fb06f
-  data.tar.gz: ace7af300cc06e1fe4dfe89d21af57444a911f29561e8ea9a5376133172682257b372277ba16da751604303936328d6eab0d2bc1fa4d5d61d6df3ff974457493
+  metadata.gz: 486be1702ab47bec0f78693a94f8a7e946c45566fca0188a52d93bf7ed54fcdc6551f0837586f39c4fc6c5701ce368660896c2236be84cf6caae956123149e52
+  data.tar.gz: 2e154353c97bafe378bd278ea74af7de472c3c6a5b747ff592ee8be0dd863011f66c40d3a343e2f08d2d3defc952dd3423d81f384293853815d3a0963dbf8be9

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: 35938528 bytes
-sha256: 52b12b9b3b58fb0f3f6438be08068270f54ff18179179a611670c144dabe8aba
+size: 38708488 bytes
+sha256: 57e4e18e36c8b5550807b59e7384df1a82f3c655544ebbe7040514c16f91f00a

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: 35937424 bytes
-sha256: b9db8588042725da1badc5086fb4a3d9e0c31c841b08648e7a96aa2a54a95913
+size: 38707144 bytes
+sha256: 834b26f7b9909eb50695ca0243106837d6f2e853644b57fec475cacebb9ad853

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: 35937392 bytes
-sha256: 575c528845059b116e9d93a2a9913529296fc1d5f41d7754177501a04a63ec71
+size: 38707136 bytes
+sha256: 02cef85a056b22d560ac68916f12379efc3ef26d9e4437211b2cb838072313f8

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: x86_64-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