lora-ruby 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c27b39620c0d4484f27a0d1d80ca4bfe85fbf4a7cc9ee85866cdbc15a1f028f0
-  data.tar.gz: 6474c3321d2fef98b602deb92d184778861b4330217ebb882569cd3b828790cc
+  metadata.gz: 9f225172245d7983494a2d5d498edc749e31629b811453667be8517d7624fde0
+  data.tar.gz: 36e8d24e24003755b36abcf34354df4c7af42125d969c27c2e76de551d2cb06d
 SHA512:
-  metadata.gz: adad8d60ecf6a6df5f7156d0176d43b2981170a57bf7d2239554b94666dd06dcb8ff551c3487025cf2f3812d4465c0f4e5ecd912ed70af97f98474104e742e99
-  data.tar.gz: 63d8a74a82179146ef6dc0c9fc7ff2b30902cee5cda9a44d157953fd61a36b74c4a89a466d4a6f1b4336b2bd6ebcf6ea5dbc14c87a7e527ca999660497f2a90f
+  metadata.gz: 48356ff0802ae5949f2d000580779c865b793dc562d8068deb92e72eefc7a2409fa9890b7a69ff336ef8c0ba2d67c27da57f253e6db2674920715b71320f7c07
+  data.tar.gz: 4446b8aac9ac26302ccb688784c6bd20f3e6f4ca80d6fb66525505c7022964f672cf9272876584672ce8b34a183708a50f9cc54e785ae75420394b365ecc43f2

data/README.md

@@ -1,6 +1,6 @@
 # lora-ruby
 
-Ruby bindings for the [Lora](../../README.md) in-memory graph engine.
+Ruby bindings for the [Lora](../../README.md) graph engine.
 Ships a native extension built with [Magnus](https://github.com/matsadler/magnus)
 on top of [`rb-sys`](https://github.com/oxidize-rb/rb-sys) so the Rust
 engine runs in-process — no separate server, no socket hop.
@@ -39,6 +39,16 @@ result["rows"].each do |row|
 end
 ```
 
+Initialization rule:
+
+```ruby
+scratch = LoraRuby::Database.create         # in-memory
+persistent = LoraRuby::Database.create("./app") # persistent: directory string
+```
+
+If you want persistence, pass a directory string to
+`LoraRuby::Database.create(...)` or `LoraRuby::Database.new(...)`.
+
 ### Params
 
 `execute` accepts a second argument — either `nil` or a `Hash` keyed by
@@ -66,8 +76,8 @@ binding's `lora_python.Database` and because it mirrors the
 ## Public API
 
 ```ruby
-LoraRuby::Database.create            # -> Database
-LoraRuby::Database.new               # -> Database  (alias of .create)
+LoraRuby::Database.create(wal_dir = nil)  # -> Database
+LoraRuby::Database.new(wal_dir = nil)     # -> Database  (alias of .create)
 
 db.execute(query, params = nil)       # -> { "columns" => [...], "rows" => [...] }
 db.clear                              # -> nil
@@ -136,6 +146,20 @@ db.execute(
 - `LoraRuby::QueryError` — parse / analyze / execute failure.
 - `LoraRuby::InvalidParamsError` — a parameter value couldn't be mapped.
 
+## Persistence
+
+`LoraRuby::Database.create("./app")` and
+`LoraRuby::Database.new("./app")` open or create a WAL-backed
+persistent database rooted at that directory. Reopening the same path
+replays committed writes before returning the handle.
+
+Call `db.close` before reopening the same WAL directory inside one
+process.
+
+This first Ruby persistence slice intentionally stays small: the
+binding exposes WAL-backed initialization plus the existing snapshot
+APIs, but not checkpoint, truncate, status, or sync-mode controls.
+
 ## Concurrency (GVL release)
 
 `Database#execute` calls `rb_thread_call_without_gvl`, so other Ruby

data/lib/lora_ruby/version.rb

@@ -10,5 +10,5 @@ module LoraRuby
   # Guard against redefinition so re-requiring this file (or loading
   # both paths) doesn't emit a "warning: already initialized constant"
   # when the native extension loads second with the identical value.
-  VERSION = "0.3.0" unless const_defined?(:VERSION)
+  VERSION = "0.4.0" unless const_defined?(:VERSION)
 end

data/src/lib.rs

@@ -16,7 +16,7 @@
 use std::collections::BTreeMap;
 use std::ffi::c_void;
 use std::mem::MaybeUninit;
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
 
 use magnus::{
     function, method, prelude::*, r_hash::ForEach, value::ReprValue, Error as MagnusError,
@@ -25,6 +25,7 @@ use magnus::{
 
 use lora_database::{
     Database as InnerDatabase, ExecuteOptions, InMemoryGraph, LoraValue, QueryResult, ResultFormat,
+    WalConfig,
 };
 use lora_store::{
     LoraDate, LoraDateTime, LoraDuration, LoraLocalDateTime, LoraLocalTime, LoraPoint, LoraTime,
@@ -60,10 +61,11 @@ fn init(ruby: &Ruby) -> Result<(), MagnusError> {
     lora_ruby.define_class("InvalidParamsError", error)?;
 
     let database = lora_ruby.define_class("Database", ruby.class_object())?;
-    database.define_singleton_method("create", function!(database_create, 0))?;
-    database.define_singleton_method("new", function!(database_new, 0))?;
+    database.define_singleton_method("create", function!(database_create, -1))?;
+    database.define_singleton_method("new", function!(database_new, -1))?;
     database.define_method("execute", method!(database_execute, -1))?;
     database.define_method("clear", method!(database_clear, 0))?;
+    database.define_method("close", method!(database_close, 0))?;
     database.define_method("node_count", method!(database_node_count, 0))?;
     database.define_method(
         "relationship_count",
@@ -114,20 +116,20 @@ fn invalid_params(ruby: &Ruby, msg: impl Into<String>) -> MagnusError {
 // Database
 // ============================================================================
 
-/// In-memory Lora graph database handle exposed to Ruby.
+/// Lora graph database handle exposed to Ruby.
 ///
 /// Wraps an `Arc<Database<InMemoryGraph>>`; the same handle is cloned
 /// across the GVL-release boundary for query execution without borrowing
 /// any Ruby state.
 #[magnus::wrap(class = "LoraRuby::Database", free_immediately, size)]
 struct Database {
-    db: Arc<InnerDatabase<InMemoryGraph>>,
+    db: Mutex<Option<Arc<InnerDatabase<InMemoryGraph>>>>,
 }
 
 impl Database {
-    fn empty() -> Self {
+    fn from_db(db: Arc<InnerDatabase<InMemoryGraph>>) -> Self {
         Self {
-            db: Arc::new(InnerDatabase::in_memory()),
+            db: Mutex::new(Some(db)),
         }
     }
 }
@@ -135,32 +137,52 @@ impl Database {
 // Constructors — we expose `Database.create` and `Database.new` as
 // singletons so callers can use whichever idiom they prefer; both are
 // cost-equivalent.
-fn database_new() -> Database {
-    Database::empty()
+fn database_new(ruby: &Ruby, args: &[Value]) -> Result<Database, MagnusError> {
+    let wal_dir = optional_wal_dir_arg(ruby, args)?;
+    let db = without_gvl(move || open_database(wal_dir)).map_err(|e| query_error(ruby, e))?;
+    Ok(Database::from_db(db))
 }
 
-fn database_create() -> Database {
-    Database::empty()
+fn database_create(ruby: &Ruby, args: &[Value]) -> Result<Database, MagnusError> {
+    database_new(ruby, args)
 }
 
-fn database_clear(rb_self: &Database) {
-    rb_self.db.clear();
+fn database_clear(ruby: &Ruby, rb_self: &Database) -> Result<(), MagnusError> {
+    database_inner(ruby, rb_self)?.clear();
+    Ok(())
+}
+
+fn database_close(ruby: &Ruby, rb_self: &Database) -> Result<(), MagnusError> {
+    let mut slot = rb_self
+        .db
+        .lock()
+        .map_err(|_| query_error(ruby, "database lock poisoned"))?;
+    slot.take();
+    Ok(())
 }
 
-fn database_node_count(rb_self: &Database) -> u64 {
-    rb_self.db.node_count() as u64
+fn database_node_count(ruby: &Ruby, rb_self: &Database) -> Result<u64, MagnusError> {
+    Ok(database_inner(ruby, rb_self)?.node_count() as u64)
 }
 
-fn database_relationship_count(rb_self: &Database) -> u64 {
-    rb_self.db.relationship_count() as u64
+fn database_relationship_count(ruby: &Ruby, rb_self: &Database) -> Result<u64, MagnusError> {
+    Ok(database_inner(ruby, rb_self)?.relationship_count() as u64)
 }
 
 fn database_inspect(rb_self: &Database) -> String {
-    format!(
-        "#<LoraRuby::Database nodes={} relationships={}>",
-        rb_self.db.node_count(),
-        rb_self.db.relationship_count(),
-    )
+    match rb_self
+        .db
+        .lock()
+        .ok()
+        .and_then(|slot| slot.as_ref().cloned())
+    {
+        Some(db) => format!(
+            "#<LoraRuby::Database nodes={} relationships={}>",
+            db.node_count(),
+            db.relationship_count(),
+        ),
+        None => "#<LoraRuby::Database closed>".to_string(),
+    }
 }
 
 fn database_save_snapshot(
@@ -169,7 +191,7 @@ fn database_save_snapshot(
     path: RString,
 ) -> Result<RHash, MagnusError> {
     let path = path.to_string()?;
-    let db = Arc::clone(&rb_self.db);
+    let db = database_inner(ruby, rb_self)?;
     let meta = without_gvl(move || db.save_snapshot_to(&path))
         .map_err(|e| query_error(ruby, format!("{e}")))?;
     snapshot_meta_to_rhash(ruby, meta)
@@ -181,7 +203,7 @@ fn database_load_snapshot(
     path: RString,
 ) -> Result<RHash, MagnusError> {
     let path = path.to_string()?;
-    let db = Arc::clone(&rb_self.db);
+    let db = database_inner(ruby, rb_self)?;
     let meta = without_gvl(move || db.load_snapshot_from(&path))
         .map_err(|e| query_error(ruby, format!("{e}")))?;
     snapshot_meta_to_rhash(ruby, meta)
@@ -211,6 +233,46 @@ fn snapshot_meta_to_rhash(
     Ok(h)
 }
 
+fn optional_wal_dir_arg(ruby: &Ruby, args: &[Value]) -> Result<Option<String>, MagnusError> {
+    match args.len() {
+        0 => Ok(None),
+        1 => {
+            if args[0].is_nil() {
+                Ok(None)
+            } else {
+                Ok(Some(RString::try_convert(args[0])?.to_string()?))
+            }
+        }
+        n => Err(MagnusError::new(
+            ruby.exception_arg_error(),
+            format!("wrong number of arguments (given {n}, expected 0..1)"),
+        )),
+    }
+}
+
+fn open_database(wal_dir: Option<String>) -> Result<Arc<InnerDatabase<InMemoryGraph>>, String> {
+    let db = match wal_dir {
+        Some(dir) => {
+            InnerDatabase::open_with_wal(WalConfig::enabled(dir)).map_err(|e| e.to_string())?
+        }
+        None => InnerDatabase::in_memory(),
+    };
+    Ok(Arc::new(db))
+}
+
+fn database_inner(
+    ruby: &Ruby,
+    rb_self: &Database,
+) -> Result<Arc<InnerDatabase<InMemoryGraph>>, MagnusError> {
+    let slot = rb_self
+        .db
+        .lock()
+        .map_err(|_| query_error(ruby, "database lock poisoned"))?;
+    slot.as_ref()
+        .cloned()
+        .ok_or_else(|| query_error(ruby, "database is closed"))
+}
+
 /// `execute(query, params = nil)` — `-1` arity so `params` is optional and
 /// we can distinguish "not passed" from `nil`/`{}` (both map to empty
 /// params). Everything that touches Ruby values happens under the GVL;
@@ -248,7 +310,7 @@ fn database_execute(ruby: &Ruby, rb_self: &Database, args: &[Value]) -> Result<R
     // Run the engine with the GVL released. Everything inside the closure
     // is pure Rust — no Ruby values cross the boundary — which keeps this
     // sound.
-    let db = Arc::clone(&rb_self.db);
+    let db = database_inner(ruby, rb_self)?;
     let exec_result = without_gvl(move || {
         let options = ExecuteOptions {
             format: ResultFormat::RowArrays,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - LoraDB, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys