slatedb 0.2.0 → 0.4.4

data/ext/slatedb/src/reader.rs

@@ -4,12 +4,13 @@ use magnus::prelude::*;
 use magnus::{function, method, Error, RHash, Ruby};
 use slatedb::config::{DbReaderOptions, DurabilityLevel, ReadOptions, ScanOptions};
 use slatedb::DbReader;
+use slatedb::DbReaderMode;
+use slatedb::IterationOrder;
 
 use crate::errors::invalid_argument_error;
 use crate::iterator::Iterator;
-use crate::merge_ops::parse_merge_operator;
 use crate::runtime::block_on_result;
-use crate::utils::{get_optional, resolve_object_store};
+use crate::utils::{get_optional, prefix_subrange_from_kwargs, resolve_object_store};
 
 /// Ruby wrapper for SlateDB Reader.
 ///
@@ -26,8 +27,20 @@ impl Reader {
     /// # Arguments
     /// * `path` - The path identifier for the database
     /// * `url` - Optional object store URL
-    /// * `checkpoint_id` - Optional checkpoint UUID to read at
-    /// * `kwargs` - Additional options (manifest_poll_interval, checkpoint_lifetime, max_memtable_bytes, merge_operator)
+    /// * `checkpoint_id` - Optional checkpoint UUID to read at. When set, the reader
+    ///   is pinned to that checkpoint ([`DbReaderMode::Checkpoint`]).
+    /// * `kwargs` - Additional options (manifest_poll_interval, checkpoint_lifetime,
+    ///   max_memtable_bytes, skip_wal_replay, cache_root, max_open_file_handles,
+    ///   follow_latest).
+    ///   The local disk cache (and therefore `max_open_file_handles`) is only active
+    ///   when `cache_root` is set.
+    ///
+    ///   When neither `checkpoint_id` nor `follow_latest` is given the reader defaults
+    ///   to [`DbReaderMode::ManagedCheckpoint`], creating and periodically refreshing
+    ///   its own checkpoint so garbage collection cannot delete objects out from under
+    ///   it. Setting `follow_latest: true` selects [`DbReaderMode::FollowLatest`], which
+    ///   tails the latest manifest without writing any checkpoint — useful for read-only
+    ///   or mirrored databases, at the cost of no protection from garbage collection.
     pub fn open(
         path: String,
         url: Option<String>,
@@ -40,24 +53,35 @@ impl Reader {
         let checkpoint_lifetime = get_optional::<u64>(&kwargs, "checkpoint_lifetime")?
             .map(std::time::Duration::from_millis);
         let max_memtable_bytes = get_optional::<u64>(&kwargs, "max_memtable_bytes")?;
-        let merge_operator = parse_merge_operator(&kwargs)?;
-
-        // Parse checkpoint_id as UUID
-        let checkpoint_uuid =
-            if let Some(id_str) = checkpoint_id {
-                Some(uuid::Uuid::parse_str(&id_str).map_err(|e| {
+        let skip_wal_replay = get_optional::<bool>(&kwargs, "skip_wal_replay")?;
+        let max_open_file_handles = get_optional::<usize>(&kwargs, "max_open_file_handles")?;
+        let cache_root = get_optional::<String>(&kwargs, "cache_root")?;
+        let follow_latest = get_optional::<bool>(&kwargs, "follow_latest")?.unwrap_or(false);
+
+        // Resolve the reader mode from checkpoint_id / follow_latest.
+        let mode = match checkpoint_id {
+            Some(id_str) => {
+                if follow_latest {
+                    return Err(invalid_argument_error(
+                        "checkpoint_id and follow_latest are mutually exclusive",
+                    ));
+                }
+                let uuid = uuid::Uuid::parse_str(&id_str).map_err(|e| {
                     invalid_argument_error(&format!("invalid checkpoint_id: {}", e))
-                })?)
-            } else {
-                None
-            };
+                })?;
+                DbReaderMode::Checkpoint(uuid)
+            }
+            None if follow_latest => DbReaderMode::FollowLatest,
+            None => DbReaderMode::ManagedCheckpoint,
+        };
 
         let reader = block_on_result(async {
-            let object_store: Arc<dyn slatedb::object_store::ObjectStore> = if let Some(ref url) = url {
-                resolve_object_store(url)?
-            } else {
-                Arc::new(slatedb::object_store::memory::InMemory::new())
-            };
+            let object_store: Arc<dyn slatedb::object_store::ObjectStore> =
+                if let Some(ref url) = url {
+                    resolve_object_store(url)?
+                } else {
+                    Arc::new(slatedb::object_store::memory::InMemory::new())
+                };
 
             let mut options = DbReaderOptions::default();
             if let Some(interval) = manifest_poll_interval {
@@ -69,11 +93,17 @@ impl Reader {
             if let Some(max_bytes) = max_memtable_bytes {
                 options.max_memtable_bytes = max_bytes;
             }
-            if let Some(merge_operator) = merge_operator {
-                options.merge_operator = Some(merge_operator);
+            if let Some(skip_replay) = skip_wal_replay {
+                options.skip_wal_replay = skip_replay;
             }
-
-            DbReader::open(path, object_store, checkpoint_uuid, options).await
+            if let Some(ref root) = cache_root {
+                options.object_store_cache_options.root_folder =
+                    Some(std::path::PathBuf::from(root));
+            }
+            if let Some(max_handles) = max_open_file_handles {
+                options.object_store_cache_options.max_open_file_handles = max_handles;
+            }
+            DbReader::open(path, object_store, mode, options).await
         })?;
 
         Ok(Self {
@@ -116,6 +146,10 @@ impl Reader {
             opts.dirty = dirty;
         }
 
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
         let result =
             block_on_result(async { self.inner.get_with_options(key.as_bytes(), &opts).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
@@ -191,6 +225,18 @@ impl Reader {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
 
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
@@ -211,7 +257,8 @@ impl Reader {
             return Err(invalid_argument_error("prefix cannot be empty"));
         }
 
-        let iter = block_on_result(async { self.inner.scan_prefix(prefix.as_bytes()).await })?;
+        let iter =
+            block_on_result(async { self.inner.scan_prefix(prefix.as_bytes(), ..).await })?;
 
         Ok(Iterator::new(iter))
     }
@@ -256,10 +303,23 @@ impl Reader {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
 
+        let subrange = prefix_subrange_from_kwargs(&kwargs)?;
         let iter = block_on_result(async {
             self.inner
-                .scan_prefix_with_options(prefix.as_bytes(), &opts)
+                .scan_prefix_with_options(prefix.as_bytes(), subrange, &opts)
                 .await
         })?;
 

data/ext/slatedb/src/snapshot.rs

@@ -5,11 +5,12 @@ use magnus::prelude::*;
 use magnus::{method, Error, RHash, Ruby};
 use slatedb::config::{DurabilityLevel, ReadOptions, ScanOptions};
 use slatedb::DbSnapshot;
+use slatedb::IterationOrder;
 
 use crate::errors::{closed_error, invalid_argument_error};
 use crate::iterator::Iterator;
 use crate::runtime::block_on_result;
-use crate::utils::get_optional;
+use crate::utils::{get_optional, prefix_subrange_from_kwargs};
 
 /// Ruby wrapper for SlateDB Snapshot.
 ///
@@ -68,6 +69,10 @@ impl Snapshot {
             opts.dirty = dirty;
         }
 
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
         let guard = self.inner.borrow();
         let snapshot = guard
             .as_ref()
@@ -143,6 +148,18 @@ impl Snapshot {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
 
         let guard = self.inner.borrow();
         let snapshot = guard
@@ -173,7 +190,7 @@ impl Snapshot {
             .as_ref()
             .ok_or_else(|| closed_error("snapshot is closed"))?;
 
-        let iter = block_on_result(async { snapshot.scan_prefix(prefix.as_bytes()).await })?;
+        let iter = block_on_result(async { snapshot.scan_prefix(prefix.as_bytes(), ..).await })?;
 
         Ok(Iterator::new(iter))
     }
@@ -218,6 +235,20 @@ impl Snapshot {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        let subrange = prefix_subrange_from_kwargs(&kwargs)?;
 
         let guard = self.inner.borrow();
         let snapshot = guard
@@ -226,7 +257,7 @@ impl Snapshot {
 
         let iter = block_on_result(async {
             snapshot
-                .scan_prefix_with_options(prefix.as_bytes(), &opts)
+                .scan_prefix_with_options(prefix.as_bytes(), subrange, &opts)
                 .await
         })?;
 

data/ext/slatedb/src/transaction.rs

@@ -6,11 +6,12 @@ use slatedb::config::{
     DurabilityLevel, MergeOptions, PutOptions, ReadOptions, ScanOptions, Ttl, WriteOptions,
 };
 use slatedb::DbTransaction;
+use slatedb::IterationOrder;
 
 use crate::errors::{closed_error, invalid_argument_error, map_error};
 use crate::iterator::Iterator;
 use crate::runtime::block_on_result;
-use crate::utils::get_optional;
+use crate::utils::{get_optional, prefix_subrange_from_kwargs};
 
 /// Ruby wrapper for SlateDB Transaction.
 ///
@@ -69,13 +70,16 @@ impl Transaction {
             opts.dirty = dirty;
         }
 
+        if let Some(cb) = get_optional::<bool>(&kwargs, "cache_blocks")? {
+            opts.cache_blocks = cb;
+        }
+
         let guard = self.inner.borrow();
         let txn = guard
             .as_ref()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        let result =
-            block_on_result(async { txn.get_with_options(key.as_bytes(), &opts).await })?;
+        let result = block_on_result(async { txn.get_with_options(key.as_bytes(), &opts).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
     }
 
@@ -155,7 +159,12 @@ impl Transaction {
     }
 
     /// Merge a value with options within the transaction.
-    pub fn merge_with_options(&self, key: String, value: String, kwargs: RHash) -> Result<(), Error> {
+    pub fn merge_with_options(
+        &self,
+        key: String,
+        value: String,
+        kwargs: RHash,
+    ) -> Result<(), Error> {
         if key.is_empty() {
             return Err(invalid_argument_error("key cannot be empty"));
         }
@@ -244,6 +253,18 @@ impl Transaction {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
 
         let guard = self.inner.borrow();
         let txn = guard
@@ -274,7 +295,7 @@ impl Transaction {
             .as_ref()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        let iter = block_on_result(async { txn.scan_prefix(prefix.as_bytes()).await })?;
+        let iter = block_on_result(async { txn.scan_prefix(prefix.as_bytes(), ..).await })?;
 
         Ok(Iterator::new(iter))
     }
@@ -319,14 +340,30 @@ impl Transaction {
         if let Some(mft) = get_optional::<usize>(&kwargs, "max_fetch_tasks")? {
             opts.max_fetch_tasks = mft;
         }
+        if let Some(order) = get_optional::<String>(&kwargs, "order")? {
+            opts.order = match order.as_str() {
+                "ascending" | "asc" => IterationOrder::Ascending,
+                "descending" | "desc" => IterationOrder::Descending,
+                other => {
+                    return Err(invalid_argument_error(&format!(
+                        "invalid order: {} (expected 'asc' or 'desc')",
+                        other
+                    )))
+                }
+            };
+        }
+
+        let subrange = prefix_subrange_from_kwargs(&kwargs)?;
 
         let guard = self.inner.borrow();
         let txn = guard
             .as_ref()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        let iter =
-            block_on_result(async { txn.scan_prefix_with_options(prefix.as_bytes(), &opts).await })?;
+        let iter = block_on_result(async {
+            txn.scan_prefix_with_options(prefix.as_bytes(), subrange, &opts)
+                .await
+        })?;
 
         Ok(Iterator::new(iter))
     }
@@ -365,7 +402,11 @@ impl Transaction {
     /// Commit the transaction with options.
     pub fn commit_with_options(&self, kwargs: RHash) -> Result<(), Error> {
         let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
-        let write_opts = WriteOptions { await_durable };
+        let seqnum = get_optional::<u64>(&kwargs, "seqnum")?.unwrap_or(0);
+        let write_opts = WriteOptions {
+            await_durable,
+            seqnum,
+        };
 
         let txn = self
             .inner
@@ -422,7 +463,7 @@ pub fn define_transaction_class(ruby: &Ruby, module: &magnus::RModule) -> Result
         method!(Transaction::scan_prefix_with_options, 2),
     )?;
     class.define_method("_mark_read", method!(Transaction::mark_read, 1))?;
-    class.define_method("commit", method!(Transaction::commit, 0))?;
+    class.define_method("_commit", method!(Transaction::commit, 0))?;
     class.define_method(
         "_commit_with_options",
         method!(Transaction::commit_with_options, 1),

data/ext/slatedb/src/utils.rs

@@ -1,10 +1,14 @@
+use std::ops::Bound;
 use std::sync::Arc;
 
 use magnus::value::ReprValue;
 use magnus::{Error, RHash, Ruby, TryConvert};
 use slatedb::object_store::aws::AmazonS3Builder;
-use slatedb::object_store::{Error as ObjectStoreError, ObjectStore, ObjectStoreScheme};
-use slatedb::{Db, Error as SlateError};
+use slatedb::object_store::prefix::PrefixStore;
+use slatedb::object_store::{
+    parse_url_opts, Error as ObjectStoreError, ObjectStore, ObjectStoreScheme,
+};
+use slatedb::Error as SlateError;
 use url::Url;
 
 /// Helper to extract an optional value from an RHash
@@ -23,6 +27,30 @@ pub fn get_optional<T: TryConvert>(hash: &RHash, key: &str) -> Result<Option<T>,
     }
 }
 
+/// A key sub-range for a prefix scan, expressed as owned byte bounds. This
+/// implements `slatedb::bytes_range::ByteRangeBounds`, so it can be passed
+/// straight to `scan_prefix`/`scan_prefix_with_options`.
+pub type PrefixSubrange = (Bound<Vec<u8>>, Bound<Vec<u8>>);
+
+/// Build a suffix sub-range (relative to a scan prefix) from optional
+/// `subrange_from` / `subrange_to` keyword arguments.
+///
+/// The bounds are key *suffixes* appended to the prefix: `subrange_from` is an
+/// inclusive lower bound and `subrange_to` is an exclusive upper bound. A
+/// missing bound is unbounded, so an empty hash yields a full-prefix scan
+/// (equivalent to `..`).
+pub fn prefix_subrange_from_kwargs(hash: &RHash) -> Result<PrefixSubrange, Error> {
+    let start = match get_optional::<String>(hash, "subrange_from")? {
+        Some(s) => Bound::Included(s.into_bytes()),
+        None => Bound::Unbounded,
+    };
+    let end = match get_optional::<String>(hash, "subrange_to")? {
+        Some(s) => Bound::Excluded(s.into_bytes()),
+        None => Bound::Unbounded,
+    };
+    Ok((start, end))
+}
+
 /// Convert an object_store error to a SlateDB error
 fn to_slate_error(e: ObjectStoreError) -> SlateError {
     SlateError::unavailable(e.to_string())
@@ -52,8 +80,22 @@ pub fn resolve_object_store(url: &str) -> Result<Arc<dyn ObjectStore>, SlateErro
             Ok(Arc::new(store))
         }
         _ => {
-            // Fall back to slatedb's default resolver for other schemes
-            Db::resolve_object_store(url)
+            // SlateDB 0.14 changed `Db::resolve_object_store` to reject any URL
+            // that carries a path component (returning `InvalidObjectStorePath`),
+            // whereas 0.13 transparently wrapped it in a `PrefixStore`. Preserve
+            // the old, more forgiving behavior here so callers can keep passing a
+            // full location such as "file:///data/mydb" or "gs://bucket/prefix".
+            //
+            // Env keys are lowercased because `parse_url_opts` only recognizes
+            // lower-case option keys.
+            let env_vars = std::env::vars().map(|(k, v)| (k.to_ascii_lowercase(), v));
+            let (store, path) = parse_url_opts(&parsed_url, env_vars).map_err(to_slate_error)?;
+            let store: Arc<dyn ObjectStore> = Arc::from(store);
+            if path.as_ref().is_empty() {
+                Ok(store)
+            } else {
+                Ok(Arc::new(PrefixStore::new(store, path)))
+            }
         }
     }
 }

data/ext/slatedb/src/write_batch.rs

@@ -89,7 +89,12 @@ impl WriteBatch {
     ///
     /// Options:
     /// - ttl: Time-to-live in milliseconds
-    pub fn merge_with_options(&self, key: String, value: String, kwargs: RHash) -> Result<(), Error> {
+    pub fn merge_with_options(
+        &self,
+        key: String,
+        value: String,
+        kwargs: RHash,
+    ) -> Result<(), Error> {
         if key.is_empty() {
             return Err(invalid_argument_error("key cannot be empty"));
         }