activerecord-libsql 0.1.0

data/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["ext/turso_libsql"]
+resolver = "2"

data/README.md

@@ -0,0 +1,265 @@
+# activerecord-libsql
+
+ActiveRecord adapter for [Turso](https://turso.tech) (libSQL) database.
+
+Connects Rails/ActiveRecord models to Turso via a native Rust extension ([magnus](https://github.com/matsadler/magnus) + [libsql](https://github.com/tursodatabase/libsql)), using the libSQL remote protocol directly — no HTTP client wrapper required.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rust >= 1.70 (install via [rustup](https://rustup.rs))
+- ActiveRecord >= 7.0
+
+## Installation
+
+```ruby
+# Gemfile
+gem "activerecord-libsql"
+```
+
+```bash
+bundle install
+bundle exec rake compile
+```
+
+## Configuration
+
+### database.yml
+
+```yaml
+default: &default
+  adapter: turso
+  database: <%= ENV["TURSO_DATABASE_URL"] %>   # libsql://xxx.turso.io
+  token: <%= ENV["TURSO_AUTH_TOKEN"] %>
+
+development:
+  <<: *default
+
+production:
+  <<: *default
+```
+
+> **Note**: Use the `database:` key, not `url:`. ActiveRecord tries to resolve the adapter from the URL scheme when `url:` is used, which causes a lookup failure.
+
+### Direct connection
+
+```ruby
+require "activerecord-libsql"
+
+ActiveRecord::Base.establish_connection(
+  adapter:  "turso",
+  database: "libsql://your-db.turso.io",
+  token:    "your-auth-token"
+)
+```
+
+## Usage
+
+```ruby
+class User < ActiveRecord::Base
+end
+
+# Create
+User.create!(name: "Alice", email: "alice@example.com")
+
+# Read
+User.where(name: "Alice").first
+User.find(1)
+User.order(:name).limit(10)
+
+# Update
+User.find(1).update!(email: "new@example.com")
+
+# Delete
+User.find(1).destroy
+```
+
+## Embedded Replicas
+
+Embedded Replicas keep a local SQLite copy of your Turso database on disk, synced from the remote. Reads are served locally (sub-millisecond), writes go to the remote.
+
+### Configuration
+
+```yaml
+# database.yml
+production:
+  adapter: turso
+  database: <%= ENV["TURSO_DATABASE_URL"] %>   # libsql://xxx.turso.io
+  token: <%= ENV["TURSO_AUTH_TOKEN"] %>
+  replica_path: /var/data/myapp.db             # local replica file path
+  sync_interval: 60                            # background sync every 60 seconds (0 = manual only)
+```
+
+Or via `establish_connection`:
+
+```ruby
+ActiveRecord::Base.establish_connection(
+  adapter:       "turso",
+  database:      "libsql://your-db.turso.io",
+  token:         "your-auth-token",
+  replica_path:  "/var/data/myapp.db",
+  sync_interval: 60
+)
+```
+
+### Manual sync
+
+```ruby
+# Trigger a sync from the remote at any time
+ActiveRecord::Base.connection.sync
+```
+
+### Notes
+
+- `replica_path` must point to a clean (empty) file or a previously synced replica. Using an existing SQLite file from another source will cause an error.
+- `sync_interval` is in seconds. Set to `0` or omit to use manual sync only.
+- **Multi-process caution**: Do not share the same `replica_path` across multiple Puma workers. Each worker should use a unique path (e.g. `/var/data/myapp-worker-#{worker_id}.db`).
+- The background sync task runs as long as the `Database` object is alive. The adapter holds the `Database` for the lifetime of the connection.
+
+## Schema Management
+
+`turso:schema:apply` and `turso:schema:diff` use [sqldef](https://github.com/sqldef/sqldef) (`sqlite3def`) to manage your Turso schema declaratively — no migration files, no version tracking. You define the desired schema in a `.sql` file and the task computes and applies only the diff.
+
+### Prerequisites
+
+```bash
+# macOS
+brew install sqldef/sqldef/sqlite3def
+
+# Other platforms: https://github.com/sqldef/sqldef/releases
+```
+
+`replica_path` must be configured in `database.yml` (the tasks use the local replica to compute the diff without touching the remote directly).
+
+### turso:schema:apply
+
+Applies the diff between your desired schema and the current remote schema.
+
+```bash
+rake turso:schema:apply[db/schema.sql]
+```
+
+Example output:
+
+```
+==> [1/4] Pulling latest schema from remote...
+    Done.
+==> [2/4] Computing schema diff...
+    2 statement(s) to apply:
+      ALTER TABLE users ADD COLUMN bio TEXT;
+      CREATE INDEX idx_users_email ON users (email);
+==> [3/4] Applying schema to Turso Cloud...
+    Done.
+==> [4/4] Pulling to confirm...
+    Done.
+==> Schema applied successfully!
+```
+
+If the schema is already up to date:
+
+```
+==> [1/4] Pulling latest schema from remote...
+    Done.
+==> [2/4] Computing schema diff...
+    Already up to date.
+```
+
+### turso:schema:diff
+
+Shows what would be applied without making any changes (dry-run).
+
+```bash
+rake turso:schema:diff[db/schema.sql]
+```
+
+### schema.sql format
+
+Plain SQL `CREATE TABLE` statements. sqldef handles `ALTER TABLE` / `CREATE INDEX` / `DROP` automatically based on the diff.
+
+```sql
+CREATE TABLE users (
+  id   TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL
+);
+
+CREATE TABLE posts (
+  id         TEXT PRIMARY KEY,
+  user_id    TEXT NOT NULL,
+  title      TEXT NOT NULL,
+  body       TEXT,
+  created_at TEXT NOT NULL
+);
+```
+
+## Architecture
+
+```
+Rails Model (ActiveRecord)
+  ↓  Arel → SQL string
+LibsqlAdapter  (lib/active_record/connection_adapters/libsql_adapter.rb)
+  ↓  perform_query / exec_update
+TursoLibsql::Database + Connection  (Rust native extension)
+  ↓  libsql::Database / Connection  (async Tokio runtime → block_on)
+
+Remote mode:   Turso Cloud  (libSQL remote protocol over HTTPS)
+Replica mode:  Local SQLite file ←sync→ Turso Cloud
+```
+
+## Thread Safety
+
+`libsql::Connection` implements `Send + Sync`, making it thread-safe. ActiveRecord's `ConnectionPool` issues a separate `Adapter` instance per thread, so `@raw_connection` is never shared across threads.
+
+## Performance
+
+Benchmarked against a **Turso cloud database** (remote, over HTTPS) from a MacBook on a home network. All numbers include full round-trip network latency.
+
+| Operation | ops/sec | avg latency |
+|-----------|--------:|------------:|
+| INSERT single row | 9.9 | 101.5 ms |
+| SELECT all (100 rows) | 29.1 | 34.3 ms |
+| SELECT WHERE | 35.9 | 27.9 ms |
+| SELECT find by id | 16.2 | 61.9 ms |
+| UPDATE single row | 6.4 | 156.0 ms |
+| DELETE single row | 6.9 | 145.2 ms |
+| Transaction (10 inserts) | 1.9 | 539.0 ms |
+
+> **Environment**: Ruby 3.4.8 · ActiveRecord 8.1.2 · Turso cloud (remote) · macOS arm64  
+> Run `bundle exec ruby bench/benchmark.rb` to reproduce.
+
+Latency is dominated by network round-trips to the Turso cloud endpoint. For lower latency, use [Embedded Replicas](#embedded-replicas) — reads are served from a local SQLite file with sub-millisecond latency.
+
+## Feature Support
+
+| Feature | Status |
+|---------|--------|
+| SELECT | ✅ |
+| INSERT | ✅ |
+| UPDATE | ✅ |
+| DELETE | ✅ |
+| Transactions | ✅ |
+| Migrations (basic) | ✅ |
+| Schema management (sqldef) | ✅ |
+| Prepared statements | ✅ |
+| BLOB | ✅ |
+| NOT NULL / UNIQUE constraint errors → AR exceptions | ✅ |
+| Embedded Replica | ✅ |
+
+## Testing
+
+```bash
+# Unit tests only (no credentials needed)
+bundle exec rake spec
+
+# Integration tests (requires TURSO_DATABASE_URL and TURSO_AUTH_TOKEN)
+bundle exec rake spec:integration
+
+# All tests
+bundle exec rake spec:all
+```
+
+Set `SKIP_INTEGRATION_TESTS=1` to skip integration tests in CI environments without Turso credentials.
+
+## License
+
+MIT

data/activerecord-libsql.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'lib/activerecord/libsql/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'activerecord-libsql'
+  spec.version = ActiveRecord::Libsql::VERSION
+  spec.authors = ['aileron']
+  spec.email = []
+
+  spec.summary = 'ActiveRecord adapter for Turso (libSQL) database'
+  spec.description = <<~DESC
+    An ActiveRecord adapter for Turso, the edge SQLite database powered by libSQL.
+    Uses a native Rust extension (via magnus) to connect directly to Turso via the
+    libSQL remote protocol, without requiring any external HTTP client.
+  DESC
+  spec.homepage = 'https://github.com/aileron-inc/activerecord-libsql'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  spec.files = Dir[
+    'lib/**/*.rb',
+    'ext/**/*.{rs,toml,rb}',
+    '*.md',
+    '*.gemspec',
+    'Cargo.{toml,lock}'
+  ]
+
+  spec.require_paths = ['lib']
+  spec.extensions = ['ext/turso_libsql/extconf.rb']
+
+  spec.add_dependency 'activerecord', '>= 7.0'
+  spec.add_dependency 'rb_sys', '~> 0.9'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rake-compiler', '~> 1.2'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/ext/turso_libsql/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "turso_libsql"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "turso_libsql"
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = { version = "0.8", features = [] }
+libsql = { version = "0.9.23", features = ["encryption", "sync"] }
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros"] }
+once_cell = "1"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"

data/ext/turso_libsql/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('turso_libsql/turso_libsql')

data/ext/turso_libsql/src/lib.rs

@@ -0,0 +1,299 @@
+use magnus::{function, method, prelude::*, Error, Ruby};
+use once_cell::sync::OnceCell;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::runtime::Runtime;
+
+// グローバル Tokio ランタイム（libsql は async API のため必要）
+static RUNTIME: OnceCell<Runtime> = OnceCell::new();
+
+fn runtime() -> &'static Runtime {
+    RUNTIME.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .expect("Failed to create Tokio runtime")
+    })
+}
+
+/// async ブロック内から Ruby の RuntimeError を生成するヘルパー
+fn mk_err(msg: impl std::fmt::Display) -> Error {
+    let ruby = Ruby::get().expect("called outside Ruby thread");
+    Error::new(ruby.exception_runtime_error(), msg.to_string())
+}
+
+// -----------------------------------------------------------------------
+// TursoDatabase — Database を保持するラッパー（sync のために必要）
+// -----------------------------------------------------------------------
+
+#[magnus::wrap(class = "TursoLibsql::Database", free_immediately, size)]
+struct TursoDatabase {
+    inner: Arc<libsql::Database>,
+}
+
+impl TursoDatabase {
+    /// リモート接続用 Database を作成（既存の remote モード）
+    fn new_remote(url: String, token: String) -> Result<Self, Error> {
+        let db = runtime().block_on(async {
+            libsql::Builder::new_remote(url, token)
+                .build()
+                .await
+                .map_err(mk_err)
+        })?;
+        Ok(Self { inner: Arc::new(db) })
+    }
+
+    /// Embedded Replica 用 Database を作成
+    /// path: ローカル DB ファイルパス
+    /// url: Turso リモート URL (libsql://...)
+    /// token: 認証トークン
+    /// sync_interval_secs: バックグラウンド自動同期間隔（秒）。0 なら手動のみ
+    fn new_remote_replica(
+        path: String,
+        url: String,
+        token: String,
+        sync_interval_secs: u64,
+    ) -> Result<Self, Error> {
+        let db = runtime().block_on(async {
+            let mut builder = libsql::Builder::new_remote_replica(path, url, token);
+            if sync_interval_secs > 0 {
+                builder = builder.sync_interval(Duration::from_secs(sync_interval_secs));
+            }
+            builder.build().await.map_err(mk_err)
+        })?;
+        Ok(Self { inner: Arc::new(db) })
+    }
+
+    /// Offline write 用 Database を作成
+    /// write はローカルに書いてすぐ返す。sync() でまとめてリモートへ反映する。
+    /// path: ローカル DB ファイルパス
+    /// url: Turso リモート URL (libsql://...)
+    /// token: 認証トークン
+    /// sync_interval_secs: バックグラウンド自動同期間隔（秒）。0 なら手動のみ
+    fn new_synced(
+        path: String,
+        url: String,
+        token: String,
+        sync_interval_secs: u64,
+    ) -> Result<Self, Error> {
+        let db = runtime().block_on(async {
+            let mut builder = libsql::Builder::new_synced_database(path, url, token);
+            if sync_interval_secs > 0 {
+                builder = builder.sync_interval(Duration::from_secs(sync_interval_secs));
+            }
+            builder.build().await.map_err(mk_err)
+        })?;
+        Ok(Self { inner: Arc::new(db) })
+    }
+
+    /// リモートから最新フレームを手動で同期する（pull）
+    /// offline モードでは write もまとめてリモートへ push される
+    fn sync(&self) -> Result<(), Error> {
+        let db = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            db.sync().await.map_err(mk_err)
+        })?;
+        Ok(())
+    }
+
+    /// この Database から Connection を取得して TursoConnection を返す
+    fn connect(&self) -> Result<TursoConnection, Error> {
+        let conn = self.inner.connect().map_err(mk_err)?;
+        Ok(TursoConnection {
+            inner: Arc::new(conn),
+        })
+    }
+}
+
+// -----------------------------------------------------------------------
+// TursoConnection — Ruby に公開する接続オブジェクト
+// -----------------------------------------------------------------------
+
+#[magnus::wrap(class = "TursoLibsql::Connection", free_immediately, size)]
+struct TursoConnection {
+    inner: Arc<libsql::Connection>,
+}
+
+impl TursoConnection {
+    /// 新しいリモート接続を作成する（Ruby: TursoLibsql::Connection.new(url, token)）
+    /// 後方互換のために残す。内部では TursoDatabase を経由する
+    fn new(url: String, token: String) -> Result<Self, Error> {
+        let db = runtime().block_on(async {
+            libsql::Builder::new_remote(url, token)
+                .build()
+                .await
+                .map_err(mk_err)
+        })?;
+        let conn = db.connect().map_err(mk_err)?;
+        Ok(Self {
+            inner: Arc::new(conn),
+        })
+    }
+
+    /// SQL を実行し、影響を受けた行数を返す（INSERT/UPDATE/DELETE 用）
+    fn execute(&self, sql: String) -> Result<u64, Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            conn.execute(&sql, ()).await.map_err(mk_err)
+        })
+    }
+
+    /// SQL を実行し、結果を Array of Hash で返す（SELECT 用）
+    fn query(&self, sql: String) -> Result<magnus::RArray, Error> {
+        let conn = Arc::clone(&self.inner);
+
+        let rows_data: Vec<Vec<(String, libsql::Value)>> =
+            runtime().block_on(async move {
+                let mut rows = conn.query(&sql, ()).await.map_err(mk_err)?;
+                let mut result: Vec<Vec<(String, libsql::Value)>> = Vec::new();
+
+                while let Some(row) = rows.next().await.map_err(mk_err)? {
+                    let col_count = rows.column_count();
+                    let mut record: Vec<(String, libsql::Value)> =
+                        Vec::with_capacity(col_count as usize);
+
+                    for i in 0..col_count {
+                        let name = rows.column_name(i).unwrap_or("?").to_string();
+                        let val = row.get_value(i).map_err(mk_err)?;
+                        record.push((name, val));
+                    }
+                    result.push(record);
+                }
+                Ok::<_, Error>(result)
+            })?;
+
+        let ruby = Ruby::get().expect("called outside Ruby thread");
+        let outer = ruby.ary_new_capa(rows_data.len());
+        for record in rows_data {
+            let hash = ruby.hash_new();
+            for (col, val) in record {
+                let ruby_key = ruby.str_new(&col);
+                let ruby_val = libsql_value_to_ruby(&ruby, val)?;
+                hash.aset(ruby_key, ruby_val)?;
+            }
+            outer.push(hash)?;
+        }
+        Ok(outer)
+    }
+
+    /// プリペアドステートメントで SQL を実行（パラメータ付き）
+    fn execute_with_params(&self, sql: String, params: Vec<String>) -> Result<u64, Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            let params: Vec<libsql::Value> =
+                params.into_iter().map(libsql::Value::Text).collect();
+            conn.execute(&sql, libsql::params_from_iter(params))
+                .await
+                .map_err(mk_err)
+        })
+    }
+
+    /// トランザクションを開始する
+    fn begin_transaction(&self) -> Result<(), Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            conn.execute("BEGIN", ()).await.map_err(mk_err)
+        })?;
+        Ok(())
+    }
+
+    /// トランザクションをコミットする
+    fn commit_transaction(&self) -> Result<(), Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            conn.execute("COMMIT", ()).await.map_err(mk_err)
+        })?;
+        Ok(())
+    }
+
+    /// トランザクションをロールバックする
+    fn rollback_transaction(&self) -> Result<(), Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            conn.execute("ROLLBACK", ()).await.map_err(mk_err)
+        })?;
+        Ok(())
+    }
+
+    /// 最後に挿入した行の rowid を返す
+    fn last_insert_rowid(&self) -> Result<i64, Error> {
+        let conn = Arc::clone(&self.inner);
+        runtime().block_on(async move {
+            let mut rows = conn
+                .query("SELECT last_insert_rowid()", ())
+                .await
+                .map_err(mk_err)?;
+
+            if let Some(row) = rows.next().await.map_err(mk_err)? {
+                row.get::<i64>(0).map_err(mk_err)
+            } else {
+                Ok(0)
+            }
+        })
+    }
+}
+
+// -----------------------------------------------------------------------
+// libsql::Value → Ruby Value 変換
+// -----------------------------------------------------------------------
+
+fn libsql_value_to_ruby(ruby: &Ruby, val: libsql::Value) -> Result<magnus::Value, Error> {
+    match val {
+        libsql::Value::Null => Ok(ruby.qnil().as_value()),
+        libsql::Value::Integer(i) => Ok(ruby.integer_from_i64(i).as_value()),
+        libsql::Value::Real(f) => Ok(ruby.float_from_f64(f).as_value()),
+        libsql::Value::Text(s) => Ok(ruby.str_new(&s).as_value()),
+        libsql::Value::Blob(b) => Ok(ruby.str_from_slice(&b).as_value()),
+    }
+}
+
+// -----------------------------------------------------------------------
+// Magnus init — Ruby 拡張のエントリポイント
+// -----------------------------------------------------------------------
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("TursoLibsql")?;
+
+    // TursoLibsql::Database
+    let db_class = module.define_class("Database", ruby.class_object())?;
+    db_class.define_singleton_method("new_remote", function!(TursoDatabase::new_remote, 2))?;
+    db_class.define_singleton_method(
+        "new_remote_replica",
+        function!(TursoDatabase::new_remote_replica, 4),
+    )?;
+    db_class.define_singleton_method(
+        "new_synced",
+        function!(TursoDatabase::new_synced, 4),
+    )?;
+    db_class.define_method("sync", method!(TursoDatabase::sync, 0))?;
+    db_class.define_method("connect", method!(TursoDatabase::connect, 0))?;
+
+    // TursoLibsql::Connection
+    let conn_class = module.define_class("Connection", ruby.class_object())?;
+    conn_class.define_singleton_method("new", function!(TursoConnection::new, 2))?;
+    conn_class.define_method("execute", method!(TursoConnection::execute, 1))?;
+    conn_class.define_method("query", method!(TursoConnection::query, 1))?;
+    conn_class.define_method(
+        "execute_with_params",
+        method!(TursoConnection::execute_with_params, 2),
+    )?;
+    conn_class.define_method(
+        "begin_transaction",
+        method!(TursoConnection::begin_transaction, 0),
+    )?;
+    conn_class.define_method(
+        "commit_transaction",
+        method!(TursoConnection::commit_transaction, 0),
+    )?;
+    conn_class.define_method(
+        "rollback_transaction",
+        method!(TursoConnection::rollback_transaction, 0),
+    )?;
+    conn_class.define_method(
+        "last_insert_rowid",
+        method!(TursoConnection::last_insert_rowid, 0),
+    )?;
+
+    Ok(())
+}