libsql2 0.1.0

data/Cargo.toml

@@ -0,0 +1,7 @@
+[workspace]
+members = ["ext/libsql2"]
+resolver = "2"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+needless_pass_by_value = "allow"  # magnus callbacks require owned values

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 speria-jp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# libsql2
+
+An alternative to [turso_libsql](https://github.com/tursodatabase/libsql-ruby) with a native Rust extension.
+
+## Features
+
+- **Native Rust extension** — no FFI overhead
+- **Full libSQL support** — local files, in-memory, remote (Turso Cloud), and Embedded Replicas
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "libsql2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Opening a Database
+
+```ruby
+require "libsql2"
+
+# Local file
+db = Libsql::Database.open("/path/to/file.db")
+
+# In-memory
+db = Libsql::Database.open(":memory:")
+
+# Remote (Turso Cloud)
+db = Libsql::Database.open("libsql://xxx.turso.io", auth_token: "xxx")
+
+# Embedded Replica
+db = Libsql::Database.open("libsql://xxx.turso.io",
+  auth_token: "xxx",
+  local_path: "/path/to/replica.db",
+  sync_interval: 60,
+  read_your_writes: true
+)
+
+# Block form (auto-close)
+Libsql::Database.open(":memory:") do |db|
+  # ...
+end
+```
+
+### Querying
+
+```ruby
+db.connect do |conn|
+  conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
+  conn.execute("INSERT INTO users (name, age) VALUES (?, ?)", ["Alice", 30])
+
+  rows = conn.query("SELECT * FROM users WHERE age > ?", [20])
+  rows.columns  #=> ["id", "name", "age"]
+  rows.types    #=> ["INTEGER", "TEXT", "INTEGER"]
+  rows.each { |row| puts row["name"] }
+end
+```
+
+### Execute (no result set)
+
+```ruby
+conn.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])
+conn.changes            #=> 1
+conn.last_insert_rowid  #=> 42
+```
+
+### Batch Execution
+
+```ruby
+conn.execute_batch(<<~SQL)
+  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
+  CREATE TABLE posts (id INTEGER PRIMARY KEY, user_id INTEGER, title TEXT);
+SQL
+```
+
+### Prepared Statements
+
+```ruby
+stmt = conn.prepare("SELECT * FROM users WHERE name = ?")
+stmt.bind(["Alice"])
+rows = stmt.query
+stmt.close
+```
+
+### Transactions
+
+```ruby
+conn.transaction do |tx|
+  tx.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", [1])
+  tx.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", [2])
+  # Commits on normal exit, rolls back on exception
+end
+
+# With behavior
+conn.transaction(:immediate) do |tx|
+  tx.execute("INSERT INTO orders (item) VALUES (?)", ["widget"])
+end
+
+# Nested transactions (SAVEPOINT)
+conn.transaction do |tx|
+  tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])
+  tx.transaction do |tx2|
+    tx2.execute("INSERT INTO users (name) VALUES (?)", ["Bob"])
+  end
+end
+```
+
+### Embedded Replica Sync
+
+```ruby
+db.sync  # Manual sync
+```
+
+### Fork Safety (Puma / Unicorn)
+
+```ruby
+# puma.rb
+on_worker_boot do
+  $db.discard! if $db
+  $db = Libsql::Database.open(...)
+end
+```
+
+## Type Mapping
+
+| libSQL Type | Ruby Type | Notes |
+|---|---|---|
+| INTEGER | `Integer` | Signed 64-bit |
+| REAL | `Float` | Double precision |
+| TEXT | `String` | UTF-8 encoded |
+| BLOB | `Libsql::Blob` | `String` subclass with `ASCII-8BIT` encoding |
+| NULL | `nil` | |
+
+## Development
+
+Requirements: Ruby >= 3.1, Rust >= 1.74, and a C compiler.
+
+```bash
+bundle install       # Install Ruby dependencies
+rake compile         # Compile the Rust extension
+rake spec            # Run tests
+rake lint            # Run all linters (RuboCop + Clippy)
+rake fmt             # Auto-format all code
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/speria-jp/libsql-ruby2.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/ext/libsql2/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "libsql2"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[lints]
+workspace = true
+
+[dependencies]
+magnus = "0.8"
+libsql = "0.9"
+tokio = { version = "1", features = ["rt-multi-thread"] }

data/ext/libsql2/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("libsql/libsql2")

data/ext/libsql2/src/connection.rs

@@ -0,0 +1,239 @@
+use std::cell::RefCell;
+use std::sync::Arc;
+
+use magnus::{prelude::*, Error, RArray, RModule, RString, Ruby, TryConvert, Value};
+use tokio::runtime::Runtime;
+
+use crate::error;
+use crate::rows::Rows;
+use crate::statement::Statement;
+
+pub fn init(ruby: &Ruby, module: &RModule) -> Result<(), Error> {
+    let class = module.define_class("Connection", ruby.class_object())?;
+    class.define_method("execute", magnus::method!(Connection::execute, -1))?;
+    class.define_method(
+        "execute_batch",
+        magnus::method!(Connection::execute_batch, 1),
+    )?;
+    class.define_method("query", magnus::method!(Connection::query, -1))?;
+    class.define_method("changes", magnus::method!(Connection::changes, 0))?;
+    class.define_method(
+        "last_insert_rowid",
+        magnus::method!(Connection::last_insert_rowid, 0),
+    )?;
+    class.define_method("prepare", magnus::method!(Connection::prepare, 1))?;
+    class.define_method("close", magnus::method!(Connection::close, 0))?;
+    class.define_method("closed?", magnus::method!(Connection::is_closed, 0))?;
+
+    Ok(())
+}
+
+/// Internal state dropped together on close to release file descriptors.
+pub(crate) struct ConnectionInner {
+    pub rt: Arc<Runtime>,
+    pub conn: libsql::Connection,
+}
+
+#[magnus::wrap(class = "Libsql::Connection", free_immediately, size)]
+pub struct Connection {
+    inner: RefCell<Option<ConnectionInner>>,
+}
+
+impl Connection {
+    pub fn new(rt: Arc<Runtime>, conn: libsql::Connection) -> Self {
+        Self {
+            inner: RefCell::new(Some(ConnectionInner { rt, conn })),
+        }
+    }
+
+    fn with_inner<F, T>(&self, f: F) -> Result<T, Error>
+    where
+        F: FnOnce(&ConnectionInner) -> Result<T, Error>,
+    {
+        let inner = self.inner.borrow();
+        let inner = inner
+            .as_ref()
+            .ok_or_else(|| Error::new(error::closed_error(), "connection is closed"))?;
+        f(inner)
+    }
+
+    fn execute(&self, args: &[Value]) -> Result<u64, Error> {
+        if args.is_empty() {
+            return Err(Error::new(
+                error::libsql_error(),
+                "wrong number of arguments (given 0, expected 1..2)",
+            ));
+        }
+        let sql: String = TryConvert::try_convert(args[0])?;
+        let params = if args.len() > 1 {
+            ruby_array_to_params(&args[1])?
+        } else {
+            vec![]
+        };
+
+        self.with_inner(|inner| {
+            inner
+                .rt
+                .block_on(async { inner.conn.execute(&sql, params_to_libsql(&params)).await })
+                .map_err(error::to_error)
+        })
+    }
+
+    fn execute_batch(&self, sql: String) -> Result<(), Error> {
+        self.with_inner(|inner| {
+            inner
+                .rt
+                .block_on(async { inner.conn.execute_batch(&sql).await })
+                .map_err(error::to_error)?;
+            Ok(())
+        })
+    }
+
+    fn query(&self, args: &[Value]) -> Result<Rows, Error> {
+        if args.is_empty() {
+            return Err(Error::new(
+                error::libsql_error(),
+                "wrong number of arguments (given 0, expected 1..2)",
+            ));
+        }
+        let sql: String = TryConvert::try_convert(args[0])?;
+        let params = if args.len() > 1 {
+            ruby_array_to_params(&args[1])?
+        } else {
+            vec![]
+        };
+
+        self.with_inner(|inner| {
+            inner.rt.block_on(async {
+                let stmt = inner.conn.prepare(&sql).await.map_err(error::to_error)?;
+                let (column_names, column_types) = extract_column_meta(&stmt);
+
+                let mut rows = stmt
+                    .query(params_to_libsql(&params))
+                    .await
+                    .map_err(error::to_error)?;
+
+                let col_count = column_names.len();
+                let mut data = Vec::new();
+                while let Some(row) = rows.next().await.map_err(error::to_error)? {
+                    let mut row_data = Vec::with_capacity(col_count);
+                    for i in 0..col_count {
+                        let val = row.get_value(i as i32).map_err(error::to_error)?;
+                        row_data.push(val.into());
+                    }
+                    data.push(row_data);
+                }
+
+                Ok(Rows::new(column_names, column_types, data))
+            })
+        })
+    }
+
+    fn prepare(&self, sql: String) -> Result<Statement, Error> {
+        self.with_inner(|inner| {
+            inner.rt.block_on(async {
+                let stmt = inner.conn.prepare(&sql).await.map_err(error::to_error)?;
+                let (column_names, column_types) = extract_column_meta(&stmt);
+
+                Ok(Statement::new(
+                    Arc::clone(&inner.rt),
+                    stmt,
+                    column_names,
+                    column_types,
+                ))
+            })
+        })
+    }
+
+    fn changes(&self) -> Result<u64, Error> {
+        self.with_inner(|inner| Ok(inner.conn.changes()))
+    }
+
+    fn last_insert_rowid(&self) -> Result<i64, Error> {
+        self.with_inner(|inner| Ok(inner.conn.last_insert_rowid()))
+    }
+
+    fn close(&self) -> Result<(), Error> {
+        let _ = self.inner.borrow_mut().take();
+        Ok(())
+    }
+
+    fn is_closed(&self) -> bool {
+        self.inner.borrow().is_none()
+    }
+}
+
+/// Extract column names and declared types from a prepared statement.
+pub(crate) fn extract_column_meta(stmt: &libsql::Statement) -> (Vec<String>, Vec<Option<String>>) {
+    let columns = stmt.columns();
+    let mut names = Vec::with_capacity(columns.len());
+    let mut types = Vec::with_capacity(columns.len());
+    for col in &columns {
+        names.push(col.name().to_string());
+        types.push(col.decl_type().map(|s| s.to_uppercase()));
+    }
+    (names, types)
+}
+
+/// Parameter value holder for conversion
+pub(crate) enum ParamValue {
+    Null,
+    Integer(i64),
+    Real(f64),
+    Text(String),
+    Blob(Vec<u8>),
+}
+
+pub(crate) fn ruby_array_to_params(val: &Value) -> Result<Vec<ParamValue>, Error> {
+    let array: RArray = TryConvert::try_convert(*val)?;
+    let ruby = Ruby::get().expect("called from Ruby");
+    let mut params = Vec::with_capacity(array.len());
+    for item in array.into_iter() {
+        if item.is_nil() {
+            params.push(ParamValue::Null);
+        } else if item.is_kind_of(ruby.class_integer()) {
+            let i: i64 = TryConvert::try_convert(item)?;
+            params.push(ParamValue::Integer(i));
+        } else if item.is_kind_of(ruby.class_float()) {
+            let f: f64 = TryConvert::try_convert(item)?;
+            params.push(ParamValue::Real(f));
+        } else if is_blob(item) {
+            // Blob is a String subclass — must check before String
+            let rstr: RString = TryConvert::try_convert(item)?;
+            let bytes = unsafe { rstr.as_slice() }.to_vec();
+            params.push(ParamValue::Blob(bytes));
+        } else if item.is_kind_of(ruby.class_string()) {
+            let s: String = TryConvert::try_convert(item)?;
+            params.push(ParamValue::Text(s));
+        } else {
+            return Err(Error::new(
+                error::libsql_error(),
+                format!("unsupported parameter type: {}", unsafe {
+                    item.classname()
+                }),
+            ));
+        }
+    }
+    Ok(params)
+}
+
+fn is_blob(val: Value) -> bool {
+    val.is_kind_of(crate::rows::blob_class())
+}
+
+pub(crate) fn params_to_libsql(params: &[ParamValue]) -> libsql::params::Params {
+    if params.is_empty() {
+        return libsql::params::Params::None;
+    }
+    let values: Vec<libsql::Value> = params
+        .iter()
+        .map(|p| match p {
+            ParamValue::Null => libsql::Value::Null,
+            ParamValue::Integer(i) => libsql::Value::Integer(*i),
+            ParamValue::Real(f) => libsql::Value::Real(*f),
+            ParamValue::Text(s) => libsql::Value::Text(s.clone()),
+            ParamValue::Blob(b) => libsql::Value::Blob(b.clone()),
+        })
+        .collect();
+    libsql::params::Params::Positional(values)
+}

data/ext/libsql2/src/database.rs

@@ -0,0 +1,241 @@
+use std::cell::RefCell;
+use std::sync::Arc;
+
+use magnus::prelude::*;
+use magnus::{Error, RHash, RModule, Ruby, TryConvert, Value};
+use tokio::runtime::Runtime;
+
+use crate::connection::Connection;
+use crate::error;
+
+pub fn init(ruby: &Ruby, module: &RModule) -> Result<(), Error> {
+    let class = module.define_class("Database", ruby.class_object())?;
+    class.define_singleton_method("open", magnus::function!(Database::open, -1))?;
+    class.define_method("close", magnus::method!(Database::close, 0))?;
+    class.define_method("closed?", magnus::method!(Database::is_closed, 0))?;
+    class.define_method("sync", magnus::method!(Database::sync, 0))?;
+    class.define_method("connect", magnus::method!(Database::connect, 0))?;
+    class.define_method("discard!", magnus::method!(Database::discard, 0))?;
+
+    Ok(())
+}
+
+/// Internal state that gets dropped together on close/discard.
+struct DatabaseInner {
+    rt: Arc<Runtime>,
+    db: libsql::Database,
+}
+
+#[magnus::wrap(class = "Libsql::Database", free_immediately, size)]
+struct Database {
+    inner: RefCell<Option<DatabaseInner>>,
+}
+
+/// Extract an optional String value from a Ruby hash by symbol key.
+fn hash_get_string(hash: &RHash, key: &str) -> Result<Option<String>, Error> {
+    let ruby = Ruby::get().expect("called from Ruby");
+    let sym = ruby.to_symbol(key);
+    let val: Option<Value> = hash.lookup(sym)?;
+    match val {
+        Some(v) if v.is_nil() => Ok(None),
+        Some(v) => {
+            let s: String = TryConvert::try_convert(v)?;
+            Ok(Some(s))
+        }
+        None => Ok(None),
+    }
+}
+
+/// Extract an optional bool value from a Ruby hash by symbol key.
+fn hash_get_bool(hash: &RHash, key: &str) -> Result<Option<bool>, Error> {
+    let ruby = Ruby::get().expect("called from Ruby");
+    let sym = ruby.to_symbol(key);
+    let val: Option<Value> = hash.lookup(sym)?;
+    match val {
+        Some(v) if v.is_nil() => Ok(None),
+        Some(v) => {
+            let b: bool = TryConvert::try_convert(v)?;
+            Ok(Some(b))
+        }
+        None => Ok(None),
+    }
+}
+
+fn is_remote_url(path: &str) -> bool {
+    path.starts_with("libsql://") || path.starts_with("https://")
+}
+
+impl Database {
+    fn from_parts(rt: Runtime, db: libsql::Database) -> Self {
+        Self {
+            inner: RefCell::new(Some(DatabaseInner {
+                rt: Arc::new(rt),
+                db,
+            })),
+        }
+    }
+
+    fn with_inner<F, T>(&self, f: F) -> Result<T, Error>
+    where
+        F: FnOnce(&DatabaseInner) -> Result<T, Error>,
+    {
+        let inner = self.inner.borrow();
+        let inner = inner
+            .as_ref()
+            .ok_or_else(|| Error::new(error::closed_error(), "database is closed"))?;
+        f(inner)
+    }
+
+    fn open(args: &[Value]) -> Result<Self, Error> {
+        if args.is_empty() {
+            return Err(Error::new(
+                error::libsql_error(),
+                "wrong number of arguments (given 0, expected 1+)",
+            ));
+        }
+
+        let path: String = TryConvert::try_convert(args[0])?;
+
+        // Parse optional keyword arguments hash
+        let opts: Option<RHash> = if args.len() > 1 {
+            Some(TryConvert::try_convert(args[1])?)
+        } else {
+            None
+        };
+
+        let auth_token = if let Some(ref h) = opts {
+            hash_get_string(h, "auth_token")?
+        } else {
+            None
+        };
+        let local_path = if let Some(ref h) = opts {
+            hash_get_string(h, "local_path")?
+        } else {
+            None
+        };
+        let read_your_writes = if let Some(ref h) = opts {
+            hash_get_bool(h, "read_your_writes")?
+        } else {
+            None
+        };
+
+        if is_remote_url(&path) {
+            let token = auth_token.ok_or_else(|| {
+                Error::new(
+                    error::libsql_error(),
+                    "auth_token is required for remote connections",
+                )
+            })?;
+
+            if let Some(lp) = local_path {
+                Self::open_remote_replica(path, token, lp, read_your_writes)
+            } else {
+                Self::open_remote(path, token)
+            }
+        } else {
+            Self::open_local(path)
+        }
+    }
+
+    fn open_local(path: String) -> Result<Self, Error> {
+        // Validate parent directory exists for file paths
+        if path != ":memory:" {
+            let p = std::path::Path::new(&path);
+            if let Some(parent) = p.parent() {
+                if !parent.as_os_str().is_empty() && !parent.exists() {
+                    return Err(Error::new(
+                        error::libsql_error(),
+                        format!("directory does not exist: {}", parent.display()),
+                    ));
+                }
+            }
+        }
+
+        let rt = Runtime::new().map_err(|e| Error::new(error::libsql_error(), e.to_string()))?;
+
+        let db = rt
+            .block_on(async {
+                if path == ":memory:" {
+                    libsql::Builder::new_local(":memory:").build().await
+                } else {
+                    libsql::Builder::new_local(&path).build().await
+                }
+            })
+            .map_err(error::to_error)?;
+
+        Ok(Self::from_parts(rt, db))
+    }
+
+    fn open_remote(url: String, auth_token: String) -> Result<Self, Error> {
+        let rt = Runtime::new().map_err(|e| Error::new(error::libsql_error(), e.to_string()))?;
+
+        let db = rt
+            .block_on(async { libsql::Builder::new_remote(url, auth_token).build().await })
+            .map_err(error::to_error)?;
+
+        Ok(Self::from_parts(rt, db))
+    }
+
+    fn open_remote_replica(
+        url: String,
+        auth_token: String,
+        local_path: String,
+        read_your_writes: Option<bool>,
+    ) -> Result<Self, Error> {
+        let rt = Runtime::new().map_err(|e| Error::new(error::libsql_error(), e.to_string()))?;
+
+        let db = rt
+            .block_on(async {
+                let mut builder = libsql::Builder::new_remote_replica(local_path, url, auth_token);
+                if let Some(ryw) = read_your_writes {
+                    builder = builder.read_your_writes(ryw);
+                }
+                builder.build().await
+            })
+            .map_err(error::to_error)?;
+
+        Ok(Self::from_parts(rt, db))
+    }
+
+    fn close(&self) -> Result<(), Error> {
+        // Drop both database and runtime to release file descriptors
+        let _ = self.inner.borrow_mut().take();
+        Ok(())
+    }
+
+    fn is_closed(&self) -> bool {
+        self.inner.borrow().is_none()
+    }
+
+    fn sync(&self) -> Result<(), Error> {
+        self.with_inner(|inner| {
+            // sync is a no-op for local/in-memory databases.
+            // Only embedded replicas actually perform synchronization.
+            let result = inner.rt.block_on(async { inner.db.sync().await });
+            match result {
+                Ok(_) => Ok(()),
+                Err(libsql::Error::SyncNotSupported(_)) => Ok(()),
+                Err(e) => Err(error::to_error(e)),
+            }
+        })
+    }
+
+    fn connect(&self) -> Result<Connection, Error> {
+        self.with_inner(|inner| {
+            let conn = inner
+                .rt
+                .block_on(async { inner.db.connect() })
+                .map_err(error::to_error)?;
+
+            Ok(Connection::new(Arc::clone(&inner.rt), conn))
+        })
+    }
+
+    fn discard(&self) -> Result<(), Error> {
+        // Drop both database and runtime to release all resources.
+        // Intended for use after fork (Puma/Unicorn) to discard
+        // inherited connections that are no longer valid.
+        let _ = self.inner.borrow_mut().take();
+        Ok(())
+    }
+}