lora-ruby 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc78ad82af9cdeddda40129742a043a0a2671a4671ace27e6ed250f10bb81f47
-  data.tar.gz: 409372914f30e7c4d69ad3a4fb70dc328020a0b903c2a0c1d69b64aa61c2358f
+  metadata.gz: 9f225172245d7983494a2d5d498edc749e31629b811453667be8517d7624fde0
+  data.tar.gz: 36e8d24e24003755b36abcf34354df4c7af42125d969c27c2e76de551d2cb06d
 SHA512:
-  metadata.gz: 7fb025acfebc7f57a98cb07f745b9ad9ede8cae1532abc4a157d2fd8c0cfc875754299e714b4456dc4f93bed76b10954edb8bc6f5b41012d02f2076510a71ed0
-  data.tar.gz: 884ffd034cd6b174b936bc0c02019e073c4d3106822db1f9f8fa067fd3903a8c9dc619648508d855ee2ab26f522dab6b619c89f35be2d5c9f5fcbbfb2c5496dc
+  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.2.0" unless const_defined?(:VERSION)
+  VERSION = "0.4.0" unless const_defined?(:VERSION)
 end

data/src/lib.rs

@@ -25,10 +25,11 @@ use magnus::{
 
 use lora_database::{
     Database as InnerDatabase, ExecuteOptions, InMemoryGraph, LoraValue, QueryResult, ResultFormat,
+    WalConfig,
 };
 use lora_store::{
-    GraphStorage, LoraDate, LoraDateTime, LoraDuration, LoraLocalDateTime, LoraLocalTime,
-    LoraPoint, LoraTime, LoraVector, RawCoordinate, VectorCoordinateType, VectorValues,
+    LoraDate, LoraDateTime, LoraDuration, LoraLocalDateTime, LoraLocalTime, LoraPoint, LoraTime,
+    LoraVector, RawCoordinate, VectorCoordinateType, VectorValues,
 };
 
 // ============================================================================
@@ -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",
@@ -71,6 +73,8 @@ fn init(ruby: &Ruby) -> Result<(), MagnusError> {
     )?;
     database.define_method("inspect", method!(database_inspect, 0))?;
     database.define_method("to_s", method!(database_inspect, 0))?;
+    database.define_method("save_snapshot", method!(database_save_snapshot, 1))?;
+    database.define_method("load_snapshot", method!(database_load_snapshot, 1))?;
 
     // `LoraRuby::VERSION` is owned by `lib/lora_ruby/version.rb` so the
     // gem can expose a version before the native extension compiles
@@ -112,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.
 ///
-/// `Arc<Mutex<InMemoryGraph>>` gives us cheap cloning so the mutex guard
-/// can be sent across the GVL-release boundary without borrowing any Ruby
-/// state.
+/// 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 {
-    store: Arc<Mutex<InMemoryGraph>>,
+    db: Mutex<Option<Arc<InnerDatabase<InMemoryGraph>>>>,
 }
 
 impl Database {
-    fn empty() -> Self {
+    fn from_db(db: Arc<InnerDatabase<InMemoryGraph>>) -> Self {
         Self {
-            store: Arc::new(Mutex::new(InMemoryGraph::new())),
+            db: Mutex::new(Some(db)),
         }
     }
 }
@@ -133,36 +137,140 @@ 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) {
-    let mut guard = rb_self.store.lock().unwrap_or_else(|p| p.into_inner());
-    *guard = InMemoryGraph::new();
+fn database_clear(ruby: &Ruby, rb_self: &Database) -> Result<(), MagnusError> {
+    database_inner(ruby, rb_self)?.clear();
+    Ok(())
 }
 
-fn database_node_count(rb_self: &Database) -> u64 {
-    let guard = rb_self.store.lock().unwrap_or_else(|p| p.into_inner());
-    guard.node_count() as u64
+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_relationship_count(rb_self: &Database) -> u64 {
-    let guard = rb_self.store.lock().unwrap_or_else(|p| p.into_inner());
-    guard.relationship_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(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 {
-    let guard = rb_self.store.lock().unwrap_or_else(|p| p.into_inner());
-    format!(
-        "#<LoraRuby::Database nodes={} relationships={}>",
-        guard.node_count(),
-        guard.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(
+    ruby: &Ruby,
+    rb_self: &Database,
+    path: RString,
+) -> Result<RHash, MagnusError> {
+    let path = path.to_string()?;
+    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)
+}
+
+fn database_load_snapshot(
+    ruby: &Ruby,
+    rb_self: &Database,
+    path: RString,
+) -> Result<RHash, MagnusError> {
+    let path = path.to_string()?;
+    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)
+}
+
+fn snapshot_meta_to_rhash(
+    ruby: &Ruby,
+    meta: lora_database::SnapshotMeta,
+) -> Result<RHash, MagnusError> {
+    let h = ruby.hash_new();
+    h.aset(
+        ruby.str_new("formatVersion"),
+        ruby.integer_from_i64(meta.format_version as i64),
+    )?;
+    h.aset(
+        ruby.str_new("nodeCount"),
+        ruby.integer_from_i64(meta.node_count as i64),
+    )?;
+    h.aset(
+        ruby.str_new("relationshipCount"),
+        ruby.integer_from_i64(meta.relationship_count as i64),
+    )?;
+    match meta.wal_lsn {
+        Some(lsn) => h.aset(ruby.str_new("walLsn"), ruby.integer_from_i64(lsn as i64))?,
+        None => h.aset(ruby.str_new("walLsn"), ruby.qnil())?,
+    }
+    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
@@ -202,9 +310,8 @@ 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 store = Arc::clone(&rb_self.store);
+    let db = database_inner(ruby, rb_self)?;
     let exec_result = without_gvl(move || {
-        let db = InnerDatabase::new(store);
         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.2.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