beagle-turso 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1330a594f1ac57da72b23e18b54eab7e725165754935b738c1f2154351592882
+  data.tar.gz: e19055c30925647fee54400f58a0038883a85e21fccc55f50020610a2a0275e2
+SHA512:
+  metadata.gz: 110a98fa2e42812b091525c4f7b9a26f09f4bc19806c0310eaf48128c596df8061d142914e55fb77cd9bdcc7fe297fc0f6a8e55a627f4c2b8f11a63003c551b3
+  data.tar.gz: 50636fc7b516e13a161927f21ee147de26c34f18195c5f6b6380ceb6147071d689d09244d563dea368de66f6a82e32608145de9bf52904cad8d689ab95eb6e78

data/README.md

@@ -0,0 +1,89 @@
+# beagle-turso
+
+A Ruby driver for [Turso](https://turso.tech)'s database engine, backed by a
+native Rust extension (`beagle_turso_core`, via [Magnus](https://github.com/matsadler/magnus)/[rb_sys](https://github.com/oxidize-rb/rb-sys)).
+
+A `Database` can be opened two ways:
+
+- **Local-only** — in-memory or an on-disk file, no network involved.
+- **Synced** — a local file kept in sync with a remote Turso database via
+  `push`/`pull`.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "beagle-turso"
+```
+
+or install directly:
+
+```sh
+gem install beagle-turso
+```
+
+Installing builds the native extension via `rb_sys`/`rake-compiler`, so a
+Rust toolchain is required unless a precompiled binary gem is available for
+your platform.
+
+## Local example
+
+```ruby
+require "beagle/turso"
+
+db = Beagle::Turso::Database.open_local(":memory:")
+conn = db.connect
+
+conn.execute("CREATE TABLE users (id INTEGER, name TEXT)", [])
+conn.execute("INSERT INTO users (id, name) VALUES (?, ?)", [1, "Ada"])
+
+rows = conn.query("SELECT id, name FROM users", [])
+# => [[1, "Ada"]]
+```
+
+`execute` returns the number of affected rows (an `Integer`); `query`
+returns an `Array` of row `Array`s. Bind parameters may be `nil`, `Integer`,
+`Float`, `String` (bound as `TEXT`), or a binary `String` — one with
+`ASCII-8BIT`/`BINARY` encoding — bound as `BLOB`.
+
+## Synced example
+
+```ruby
+require "beagle/turso"
+
+db = Beagle::Turso::Database.open(
+  local_path: "/path/to/local.db",
+  remote_url: ENV.fetch("TURSO_DATABASE_URL"),
+  auth_token: ENV.fetch("TURSO_AUTH_TOKEN")
+)
+
+conn = db.connect
+conn.execute("INSERT INTO users (id, name) VALUES (?, ?)", [2, "Grace"])
+
+db.push # propagate local writes to the remote
+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`.
+
+### Durability note: writes commit on-sync, not synchronously
+
+Writes to a synced database commit to the **local** file immediately, as
+part of `execute` — they do not wait on the network. They are only
+propagated to the remote **on sync**, i.e. whenever `push` is explicitly
+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.
+
+## Credential safety
+
+`auth_token` is never included in `inspect` output or in error messages —
+confirmed by this gem's `no_secret_logging_spec.rb`.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT).

data/ext/beagle_turso/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "beagle_turso"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+beagle_turso_core = "0.1.0"

data/ext/beagle_turso/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("beagle_turso/beagle_turso")

data/ext/beagle_turso/src/lib.rs

@@ -0,0 +1,264 @@
+// Wraps beagle_turso_core's Database and Connection as persistent Ruby
+// objects, exposing a synchronous open -> connect -> execute -> query API.
+// Lifted from the proven spike at spikes/magnus-wrap/src/lib.rs (Plan 2's
+// binding proof).
+//
+// One deliberate deviation from the spike: each wrapped fn/method takes
+// `ruby: &Ruby` as its leading parameter (magnus's `function!`/`method!`
+// macros inject it automatically — see the magnus 0.8 README's "Error
+// Handling" example) instead of calling the fallible `Ruby::get()` inside
+// the body. That sidesteps the "Ruby unavailable" fallback branch, which
+// has no live `&Ruby` to call the non-deprecated `Ruby::exception_*`
+// accessors on and so would otherwise need the deprecated
+// `magnus::exception::standard_error()` free function. Net effect is
+// identical; the code is simpler and compiles with zero deprecation
+// warnings.
+
+use beagle_turso_core::{Connection, Database, OpenOptions, Value};
+use magnus::{
+    encoding::EncodingCapable, function, method, prelude::*, Error, Float, Integer, IntoValue,
+    RArray, RString, Ruby,
+};
+
+#[magnus::wrap(class = "Beagle::Turso::Database", free_immediately)]
+struct RbDatabase {
+    inner: Database,
+}
+
+#[magnus::wrap(class = "Beagle::Turso::Connection", free_immediately)]
+struct RbConnection {
+    inner: Connection,
+}
+
+fn rt_err(ruby: &Ruby, msg: String) -> Error {
+    Error::new(ruby.exception_runtime_error(), msg)
+}
+
+fn ruby_array_to_params(ruby: &Ruby, arr: RArray) -> Result<Vec<Value>, Error> {
+    // Safe: `from_value` below is a raw type check on the Ruby object (exact
+    // class match — no `to_int`/`to_f`/`to_str` coercion method dispatch), so
+    // for the sanctioned nil/Integer/Float/String inputs no arbitrary Ruby
+    // code (which could GC/mutate the array) runs during this loop; an
+    // unsupported type falls straight to the `else` arm without invoking any
+    // Ruby method at all. The binary/text split below on an `RString` is
+    // likewise native: `EncodingCapable::enc_get` is a direct
+    // `rb_enc_get_index` C call (no method dispatch). For the binary branch
+    // `as_slice` is copied into an owned `Vec` immediately, before any
+    // further Ruby call in this loop iteration, so the borrow never outlives
+    // a point where the backing string could be mutated/GC'd out from under
+    // it.
+    let items = unsafe { arr.as_slice() };
+    let ascii_8bit = ruby.ascii8bit_encindex();
+    let mut out = Vec::with_capacity(items.len());
+    for &item in items {
+        let v = if item.is_nil() {
+            Value::Null
+        } else if let Some(i) = Integer::from_value(item) {
+            Value::Integer(i.to_i64()?)
+        } else if let Some(f) = Float::from_value(item) {
+            Value::Real(f.to_f64())
+        } else if let Some(s) = RString::from_value(item) {
+            if s.enc_get() == ascii_8bit {
+                Value::Blob(unsafe { s.as_slice() }.to_vec())
+            } else {
+                Value::Text(s.to_string()?)
+            }
+        } else {
+            return Err(Error::new(
+                ruby.exception_type_error(),
+                "unsupported bind parameter type",
+            ));
+        };
+        out.push(v);
+    }
+    Ok(out)
+}
+
+fn value_to_ruby(ruby: &Ruby, v: &Value) -> magnus::Value {
+    match v {
+        Value::Null => ruby.qnil().as_value(),
+        Value::Integer(i) => (*i).into_value_with(ruby),
+        Value::Real(f) => (*f).into_value_with(ruby),
+        Value::Text(s) => s.clone().into_value_with(ruby),
+        Value::Blob(b) => ruby.str_from_slice(b).as_value(),
+    }
+}
+
+impl RbDatabase {
+    fn open_local(ruby: &Ruby, path: String) -> Result<RbDatabase, Error> {
+        let opts = OpenOptions {
+            local_path: path,
+            remote_url: None,
+            auth_token: None,
+            bootstrap_if_empty: true,
+        };
+        let db = Database::open(opts).map_err(|e| rt_err(ruby, e.to_string()))?;
+        Ok(RbDatabase { inner: db })
+    }
+
+    // Positional primitive backing the keyword-arg `Database.open` defined in
+    // Ruby (see lib/beagle/turso.rb). Kept positional so magnus can
+    // TryConvert `nil`/`String`/bool natively for each argument, instead of
+    // parsing an RHash of keyword args by hand in Rust.
+    fn open(
+        ruby: &Ruby,
+        local_path: String,
+        remote_url: Option<String>,
+        auth_token: Option<String>,
+        bootstrap_if_empty: bool,
+    ) -> Result<RbDatabase, Error> {
+        let opts = OpenOptions {
+            local_path,
+            remote_url,
+            auth_token,
+            bootstrap_if_empty,
+        };
+        let db = Database::open(opts).map_err(|e| rt_err(ruby, e.to_string()))?;
+        Ok(RbDatabase { inner: db })
+    }
+
+    fn connect(ruby: &Ruby, rb_self: &Self) -> Result<RbConnection, Error> {
+        let c = rb_self
+            .inner
+            .connect()
+            .map_err(|e| rt_err(ruby, e.to_string()))?;
+        Ok(RbConnection { inner: c })
+    }
+
+    fn push(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self
+            .inner
+            .push()
+            .map_err(|e| rt_err(ruby, e.to_string()))
+    }
+
+    fn pull(ruby: &Ruby, rb_self: &Self) -> Result<bool, Error> {
+        rb_self
+            .inner
+            .pull()
+            .map_err(|e| rt_err(ruby, e.to_string()))
+    }
+
+    // Release the underlying engine handle and, for a synced database, end its
+    // remote sync session, instead of waiting for GC. Idempotent.
+    fn close(_ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self.inner.close();
+        Ok(())
+    }
+
+    fn is_closed(_ruby: &Ruby, rb_self: &Self) -> bool {
+        rb_self.inner.is_closed()
+    }
+}
+
+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)
+            .map_err(|e| rt_err(ruby, e.to_string()))
+    }
+
+    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)
+            .map_err(|e| rt_err(ruby, e.to_string()))?;
+        let out = ruby.ary_new();
+        for row in rows {
+            let rb_row = ruby.ary_new();
+            for val in &row.values {
+                rb_row.push(value_to_ruby(ruby, val))?;
+            }
+            out.push(rb_row)?;
+        }
+        Ok(out)
+    }
+
+    // Like `query`, but also returns column names — needed by callers (e.g.
+    // an ActiveRecord adapter) that must know column identity, not just
+    // positional values. Returns a 2-element `[columns, rows]` array;
+    // `rows` is built with the same loop `query` uses.
+    fn query_result(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sql: String,
+        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| rt_err(ruby, e.to_string()))?;
+        let columns = ruby.ary_new();
+        for name in &result.columns {
+            columns.push(name.clone().into_value_with(ruby))?;
+        }
+        let rows = ruby.ary_new();
+        for row in result.rows {
+            let rb_row = ruby.ary_new();
+            for val in &row.values {
+                rb_row.push(value_to_ruby(ruby, val))?;
+            }
+            rows.push(rb_row)?;
+        }
+        let out = ruby.ary_new();
+        out.push(columns)?;
+        out.push(rows)?;
+        Ok(out)
+    }
+
+    fn last_insert_rowid(ruby: &Ruby, rb_self: &Self) -> Result<i64, Error> {
+        rb_self
+            .inner
+            .last_insert_rowid()
+            .map_err(|e| rt_err(ruby, e.to_string()))
+    }
+
+    fn execute_batch(ruby: &Ruby, rb_self: &Self, sql: String) -> Result<(), Error> {
+        rb_self
+            .inner
+            .execute_batch(&sql)
+            .map_err(|e| rt_err(ruby, e.to_string()))
+    }
+
+    // Release the underlying connection handle instead of waiting for GC.
+    // Idempotent.
+    fn close(_ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self.inner.close();
+        Ok(())
+    }
+
+    fn is_closed(_ruby: &Ruby, rb_self: &Self) -> bool {
+        rb_self.inner.is_closed()
+    }
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let turso = ruby.define_module("Beagle")?.define_module("Turso")?;
+    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
+    // lives in Ruby (lib/beagle/turso.rb) and delegates here.
+    db.define_singleton_method("_open", function!(RbDatabase::open, 4))?;
+    db.define_method("connect", method!(RbDatabase::connect, 0))?;
+    db.define_method("push", method!(RbDatabase::push, 0))?;
+    db.define_method("pull", method!(RbDatabase::pull, 0))?;
+    db.define_method("close", method!(RbDatabase::close, 0))?;
+    db.define_method("closed?", method!(RbDatabase::is_closed, 0))?;
+    let conn = turso.define_class("Connection", ruby.class_object())?;
+    conn.define_method("execute", method!(RbConnection::execute, 2))?;
+    conn.define_method("query", method!(RbConnection::query, 2))?;
+    conn.define_method("query_result", method!(RbConnection::query_result, 2))?;
+    conn.define_method(
+        "last_insert_rowid",
+        method!(RbConnection::last_insert_rowid, 0),
+    )?;
+    conn.define_method("execute_batch", method!(RbConnection::execute_batch, 1))?;
+    conn.define_method("close", method!(RbConnection::close, 0))?;
+    conn.define_method("closed?", method!(RbConnection::is_closed, 0))?;
+    Ok(())
+}

data/lib/beagle/turso/version.rb

@@ -0,0 +1,5 @@
+module Beagle
+  module Turso
+    VERSION = "0.1.0"
+  end
+end

data/lib/beagle/turso.rb

@@ -0,0 +1,18 @@
+require_relative "turso/version"
+require "beagle_turso/beagle_turso" # native extension
+
+module Beagle
+  module Turso
+    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
+      # `#push`/`#pull`). Delegates to the native `_open` primitive, which
+      # takes its arguments positionally.
+      def self.open(local_path:, remote_url: nil, auth_token: nil, bootstrap_if_empty: true)
+        _open(local_path, remote_url, auth_token, bootstrap_if_empty)
+      end
+
+      private_class_method :_open
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: beagle-turso
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BeagleSoftwareUK
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  A Ruby driver for Turso's database engine, backed by a native Rust
+  extension (beagle_turso_core, via Magnus/rb-sys). Opens a local-only
+  database (in-memory or on-disk) or one kept in sync with a remote Turso
+  database via explicit push/pull. Writes are durable to the local file
+  immediately as they happen; push is what propagates them to the remote
+  on sync, not synchronously with every write.
+email:
+executables: []
+extensions:
+- ext/beagle_turso/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/beagle_turso/Cargo.toml
+- ext/beagle_turso/extconf.rb
+- ext/beagle_turso/src/lib.rs
+- lib/beagle/turso.rb
+- lib/beagle/turso/version.rb
+homepage: https://github.com/BeagleSoftwareUK/beagle-turso
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/BeagleSoftwareUK/beagle-turso
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby driver for Turso's new engine, backed by beagle_turso_core (Rust).
+test_files: []