slatedb 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06b42247a14342b9550a9a10641900546ea79fd52001f4b98798e028f7f03cd4
-  data.tar.gz: f83cd6b19a0f4dea849e628068c8d3e4af338b0efe320870cc8ddd5e3d55fb8c
+  metadata.gz: c93234ef6d9251d54b90cd816983c1d073d159587ae655fbef8e4e3b433928a3
+  data.tar.gz: 0b7aa7b9137ff2228f7e4153da2daafbb235ce857b51faa8d552c55f18cb7e7a
 SHA512:
-  metadata.gz: 6946b78b9f03073aee23c604443fa38fbe728c2298cba21b621d632c2d1e93d909fb900571eb976d638ac93c4e1efdfa372eb5fefd90d3e3db250f02cf3343b4
-  data.tar.gz: f161ed22a27ef14b899ec557bfdb4dadf39cc928f35e771a6e5025cc5840210109f05ea080349b7d57dc27b278c816c8e2bd842d1854937800ee772139c68a0f
+  metadata.gz: 54cc3a48576fc4ca07dc6ae95a755aa6fc5dd7fa7af46eba3452f3465c74d005d9f29d06ac1cc9ddf3461d602d910d63a08f55b0d486140ed22024f3ce1e3e4e
+  data.tar.gz: 2bd1c37ca9fcfa737bd47fd3d76b136376819b573a08e044c06114f5555d5243e8b465b7bbc8cba02f3461982cc5ea1e4195fb31e53a5f0d4dcd608d1ea79f55

data/README.md

@@ -2,35 +2,15 @@
 
 Ruby bindings for [SlateDB](https://slatedb.io), a cloud-native embedded key-value store built on object storage.
 
-[![Build status](https://badge.buildkite.com/a7ae51f3a0bc7809cf66981641ec47b3c70db8cf349a5e462f.svg)](https://buildkite.com/catkins-test/slatedb-rb)
+[![Build status](https://badge.buildkite.com/a7ae51f3a0bc7809cf66981641ec47b3c70db8cf349a5e462f.svg)](https://buildkite.com/catkins-test/slatedb-rb) [![Gem Version](https://badge.fury.io/rb/slatedb.svg)](https://badge.fury.io/rb/slatedb)
 
-## Thread Safety
+## Production Readiness
 
-**SlateDB is fully thread-safe and optimized for concurrent access.**
+These bindings are still in early development, and while SlateDB itself is used in Production, these bindings have yet to be. Contributions are welcome!
 
-- The `Database` class can be safely shared across multiple Ruby threads
-- All operations (get, put, delete, scan, transactions) are thread-safe
-- The Ruby bindings release the Global VM Lock (GVL) during I/O operations, allowing other Ruby threads to run concurrently
-- Perfect for use with multi-threaded Ruby applications like Puma, Sidekiq, and concurrent test suites
+### TODO
 
-```ruby
-db = SlateDb::Database.open("/tmp/mydb")
-
-# Safe to use from multiple threads
-threads = 10.times.map do |i|
-  Thread.new do
-    db.put("key-#{i}", "value-#{i}")
-    db.get("key-#{i}")
-  end
-end
-
-threads.each(&:join)
-```
-
-**Implementation details:**
-- The underlying SlateDB library uses `Arc` (atomic reference counting) and `RwLock` for internal state management
-- I/O operations release the Ruby GVL using `rb_thread_call_without_gvl`, preventing blocking other threads
-- A shared Tokio multi-threaded runtime handles all async operations efficiently
+- [ ] Cross-compile native extensions
 
 ## Installation
 
@@ -52,6 +32,9 @@ Or install it yourself as:
 gem install slatedb
 ```
 
+> [!IMPORTANT]
+> This gem currently requires a working Rust toolchain to install until the dependencies are cross-compiled.
+
 ## Usage
 
 ### Basic Operations
@@ -347,6 +330,34 @@ db.put("key", "value")
 db.flush
 ```
 
+## Thread Safety
+
+**SlateDB is fully thread-safe and optimized for concurrent access.**
+
+- The `Database` class can be safely shared across multiple Ruby threads
+- All operations (get, put, delete, scan, transactions) are thread-safe
+- The Ruby bindings release the Global VM Lock (GVL) during I/O operations, allowing other Ruby threads to run concurrently
+- Perfect for use with multi-threaded Ruby applications like Puma, Sidekiq, and concurrent test suites
+
+```ruby
+db = SlateDb::Database.open("/tmp/mydb")
+
+# Safe to use from multiple threads
+threads = 10.times.map do |i|
+  Thread.new do
+    db.put("key-#{i}", "value-#{i}")
+    db.get("key-#{i}")
+  end
+end
+
+threads.each(&:join)
+```
+
+**Implementation details:**
+- The underlying SlateDB library uses `Arc` (atomic reference counting) and `RwLock` for internal state management
+- I/O operations release the Ruby GVL using `rb_thread_call_without_gvl`, preventing blocking other threads
+- A shared Tokio multi-threaded runtime handles all async operations efficiently
+
 ## Error Handling
 
 SlateDB defines several exception classes:
@@ -399,6 +410,8 @@ bundle exec rspec spec/transaction_spec.rb
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/catkins/slatedb-rb.
 
+Also, find me on the [SlateDB Discord Server](https://discord.gg/mHYmGy5MgA).
+
 ## License
 
 Apache-2.0

data/ext/slatedb/Cargo.toml

@@ -16,7 +16,8 @@ magnus = { version = "0.8", features = ["rb-sys"] }
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
 tokio = { version = "1", features = ["rt-multi-thread", "sync"] }
 bytes = "1"
-object_store = "0.12"
+object_store = { version = "0.12", features = ["aws"] }
+url = "2"
 once_cell = "1"
 log = "0.4"
 uuid = "1"

data/ext/slatedb/src/admin.rs

@@ -5,9 +5,9 @@ use magnus::{function, method, Error, RHash, Ruby};
 use slatedb::admin::AdminBuilder;
 use slatedb::config::{CheckpointOptions, GarbageCollectorOptions};
 
-use crate::errors::{invalid_argument_error, map_error};
-use crate::runtime::block_on;
-use crate::utils::get_optional;
+use crate::errors::invalid_argument_error;
+use crate::runtime::{block_on, block_on_result};
+use crate::utils::{get_optional, resolve_object_store};
 
 /// Ruby wrapper for SlateDB Admin.
 ///
@@ -25,16 +25,13 @@ impl Admin {
     /// * `path` - The path identifier for the database
     /// * `url` - Optional object store URL
     pub fn new(path: String, url: Option<String>) -> Result<Self, Error> {
-        let admin = block_on(async {
-            let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
-                slatedb::Db::resolve_object_store(url).map_err(map_error)?
-            } else {
-                Arc::new(object_store::memory::InMemory::new())
-            };
-
-            Ok::<_, Error>(AdminBuilder::new(path, object_store).build())
-        })?;
+        let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
+            block_on_result(async { resolve_object_store(url) })?
+        } else {
+            Arc::new(object_store::memory::InMemory::new())
+        };
 
+        let admin = AdminBuilder::new(path, object_store).build();
         Ok(Self { inner: admin })
     }
 
@@ -103,8 +100,8 @@ impl Admin {
             name,
         };
 
-        let result = block_on(async { self.inner.create_detached_checkpoint(&options).await })
-            .map_err(map_error)?;
+        let result =
+            block_on_result(async { self.inner.create_detached_checkpoint(&options).await })?;
 
         let ruby = Ruby::get().expect("Ruby runtime not available");
         let hash = ruby.hash_new();
@@ -158,12 +155,11 @@ impl Admin {
 
         let lifetime_duration = lifetime.map(std::time::Duration::from_millis);
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .refresh_checkpoint(checkpoint_uuid, lifetime_duration)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -176,9 +172,7 @@ impl Admin {
         let checkpoint_uuid = uuid::Uuid::parse_str(&id)
             .map_err(|e| invalid_argument_error(&format!("invalid checkpoint UUID: {}", e)))?;
 
-        block_on(async { self.inner.delete_checkpoint(checkpoint_uuid).await })
-            .map_err(map_error)?;
-
+        block_on_result(async { self.inner.delete_checkpoint(checkpoint_uuid).await })?;
         Ok(())
     }
 

data/ext/slatedb/src/database.rs

@@ -6,12 +6,12 @@ use slatedb::config::{DurabilityLevel, PutOptions, ReadOptions, ScanOptions, Ttl
 use slatedb::object_store::memory::InMemory;
 use slatedb::{Db, IsolationLevel};
 
-use crate::errors::{invalid_argument_error, map_error};
+use crate::errors::invalid_argument_error;
 use crate::iterator::Iterator;
-use crate::runtime::block_on;
+use crate::runtime::block_on_result;
 use crate::snapshot::Snapshot;
 use crate::transaction::Transaction;
-use crate::utils::get_optional;
+use crate::utils::{get_optional, resolve_object_store};
 use crate::write_batch::WriteBatch;
 
 /// Ruby wrapper for SlateDB database.
@@ -32,18 +32,14 @@ impl Database {
     /// # Returns
     /// A new Database instance
     pub fn open(path: String, url: Option<String>) -> Result<Self, Error> {
-        let db = block_on(async {
-            let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
-                Db::resolve_object_store(url).map_err(map_error)?
+        let db = block_on_result(async {
+            let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url_str) = url {
+                resolve_object_store(url_str)?
             } else {
-                // Use in-memory store for local testing
                 Arc::new(InMemory::new())
             };
 
-            Db::builder(path, object_store)
-                .build()
-                .await
-                .map_err(map_error)
+            Db::builder(path, object_store).build().await
         })?;
 
         Ok(Self {
@@ -65,8 +61,8 @@ impl Database {
 
         let opts = ReadOptions::default();
 
-        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
+        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()))
     }
@@ -105,8 +101,8 @@ impl Database {
             opts.dirty = dirty;
         }
 
-        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
+        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()))
     }
@@ -125,8 +121,8 @@ impl Database {
 
         let opts = ReadOptions::default();
 
-        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
+        let result =
+            block_on_result(async { self.inner.get_with_options(key.as_bytes(), &opts).await })?;
 
         Ok(result.map(|b| b.to_vec()))
     }
@@ -147,12 +143,11 @@ impl Database {
             await_durable: true,
         };
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -181,12 +176,11 @@ impl Database {
         let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
         let write_opts = WriteOptions { await_durable };
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -204,12 +198,11 @@ impl Database {
             await_durable: true,
         };
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .delete_with_options(key.as_bytes(), &write_opts)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -227,12 +220,11 @@ impl Database {
         let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
         let write_opts = WriteOptions { await_durable };
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .delete_with_options(key.as_bytes(), &write_opts)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -255,12 +247,11 @@ impl Database {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => self.inner.scan_with_options(start_bytes..end, &opts).await,
                 None => self.inner.scan_with_options(start_bytes.., &opts).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -324,12 +315,11 @@ impl Database {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => self.inner.scan_with_options(start_bytes..end, &opts).await,
                 None => self.inner.scan_with_options(start_bytes.., &opts).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -341,9 +331,7 @@ impl Database {
     /// * `batch` - The WriteBatch to write
     pub fn write(&self, batch: &WriteBatch) -> Result<(), Error> {
         let batch_inner = batch.take()?;
-
-        block_on(async { self.inner.write(batch_inner).await }).map_err(map_error)?;
-
+        block_on_result(async { self.inner.write(batch_inner).await })?;
         Ok(())
     }
 
@@ -358,12 +346,11 @@ impl Database {
 
         let batch_inner = batch.take()?;
 
-        block_on(async {
+        block_on_result(async {
             self.inner
                 .write_with_options(batch_inner, &write_opts)
                 .await
-        })
-        .map_err(map_error)?;
+        })?;
 
         Ok(())
     }
@@ -389,8 +376,7 @@ impl Database {
             }
         };
 
-        let txn = block_on(async { self.inner.begin(isolation_level).await }).map_err(map_error)?;
-
+        let txn = block_on_result(async { self.inner.begin(isolation_level).await })?;
         Ok(Transaction::new(txn))
     }
 
@@ -399,20 +385,19 @@ impl Database {
     /// # Returns
     /// A new Snapshot instance
     pub fn snapshot(&self) -> Result<Snapshot, Error> {
-        let snap = block_on(async { self.inner.snapshot().await }).map_err(map_error)?;
-
+        let snap = block_on_result(async { self.inner.snapshot().await })?;
         Ok(Snapshot::new(snap))
     }
 
     /// Flush the database to ensure durability.
     pub fn flush(&self) -> Result<(), Error> {
-        block_on(async { self.inner.flush().await }).map_err(map_error)?;
+        block_on_result(async { self.inner.flush().await })?;
         Ok(())
     }
 
     /// Close the database.
     pub fn close(&self) -> Result<(), Error> {
-        block_on(async { self.inner.close().await }).map_err(map_error)?;
+        block_on_result(async { self.inner.close().await })?;
         Ok(())
     }
 }

data/ext/slatedb/src/iterator.rs

@@ -5,11 +5,17 @@ use magnus::{method, Error, Ruby};
 use slatedb::DbIterator;
 use tokio::sync::Mutex;
 
+use crate::errors::{internal_error, invalid_argument_error, map_error};
+use crate::runtime::block_on;
+
 /// Result type for raw byte key-value pairs.
 type ByteKvResult = Result<Option<(Vec<u8>, Vec<u8>)>, Error>;
 
-use crate::errors::{internal_error, invalid_argument_error, map_error};
-use crate::runtime::block_on;
+/// Internal error type for iterator operations (converted to Ruby errors after block_on).
+enum IteratorError {
+    Closed,
+    Slate(slatedb::Error),
+}
 
 /// Ruby wrapper for SlateDB iterator.
 ///
@@ -36,14 +42,19 @@ impl Iterator {
 
         let result = block_on(async {
             let mut guard = inner.lock().await;
-            let iter = guard
-                .as_mut()
-                .ok_or_else(|| internal_error("iterator has been closed"))?;
+            match guard.as_mut() {
+                Some(iter) => iter.next().await.map_err(IteratorError::Slate),
+                None => Err(IteratorError::Closed),
+            }
+        });
 
-            iter.next().await.map_err(map_error)
-        })?;
+        let kv = match result {
+            Ok(kv) => kv,
+            Err(IteratorError::Closed) => return Err(internal_error("iterator has been closed")),
+            Err(IteratorError::Slate(e)) => return Err(map_error(e)),
+        };
 
-        Ok(result.map(|kv| {
+        Ok(kv.map(|kv| {
             (
                 String::from_utf8_lossy(&kv.key).to_string(),
                 String::from_utf8_lossy(&kv.value).to_string(),
@@ -59,14 +70,19 @@ impl Iterator {
 
         let result = block_on(async {
             let mut guard = inner.lock().await;
-            let iter = guard
-                .as_mut()
-                .ok_or_else(|| internal_error("iterator has been closed"))?;
+            match guard.as_mut() {
+                Some(iter) => iter.next().await.map_err(IteratorError::Slate),
+                None => Err(IteratorError::Closed),
+            }
+        });
 
-            iter.next().await.map_err(map_error)
-        })?;
+        let kv = match result {
+            Ok(kv) => kv,
+            Err(IteratorError::Closed) => return Err(internal_error("iterator has been closed")),
+            Err(IteratorError::Slate(e)) => return Err(map_error(e)),
+        };
 
-        Ok(result.map(|kv| (kv.key.to_vec(), kv.value.to_vec())))
+        Ok(kv.map(|kv| (kv.key.to_vec(), kv.value.to_vec())))
     }
 
     /// Seek to a specific key position.
@@ -79,16 +95,19 @@ impl Iterator {
 
         let inner = self.inner.clone();
 
-        block_on(async {
+        let result = block_on(async {
             let mut guard = inner.lock().await;
-            let iter = guard
-                .as_mut()
-                .ok_or_else(|| internal_error("iterator has been closed"))?;
-
-            iter.seek(key.as_bytes()).await.map_err(map_error)
-        })?;
+            match guard.as_mut() {
+                Some(iter) => iter.seek(key.as_bytes()).await.map_err(IteratorError::Slate),
+                None => Err(IteratorError::Closed),
+            }
+        });
 
-        Ok(())
+        match result {
+            Ok(()) => Ok(()),
+            Err(IteratorError::Closed) => Err(internal_error("iterator has been closed")),
+            Err(IteratorError::Slate(e)) => Err(map_error(e)),
+        }
     }
 
     /// Close the iterator and release resources.

data/ext/slatedb/src/reader.rs

@@ -5,10 +5,10 @@ use magnus::{function, method, Error, RHash, Ruby};
 use slatedb::config::{DbReaderOptions, DurabilityLevel, ReadOptions, ScanOptions};
 use slatedb::DbReader;
 
-use crate::errors::{invalid_argument_error, map_error};
+use crate::errors::invalid_argument_error;
 use crate::iterator::Iterator;
-use crate::runtime::block_on;
-use crate::utils::get_optional;
+use crate::runtime::block_on_result;
+use crate::utils::{get_optional, resolve_object_store};
 
 /// Ruby wrapper for SlateDB Reader.
 ///
@@ -50,9 +50,9 @@ impl Reader {
                 None
             };
 
-        let reader = block_on(async {
+        let reader = block_on_result(async {
             let object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
-                slatedb::Db::resolve_object_store(url).map_err(map_error)?
+                resolve_object_store(url)?
             } else {
                 Arc::new(object_store::memory::InMemory::new())
             };
@@ -68,9 +68,7 @@ impl Reader {
                 options.max_memtable_bytes = max_bytes;
             }
 
-            DbReader::open(path, object_store, checkpoint_uuid, options)
-                .await
-                .map_err(map_error)
+            DbReader::open(path, object_store, checkpoint_uuid, options).await
         })?;
 
         Ok(Self {
@@ -84,8 +82,7 @@ impl Reader {
             return Err(invalid_argument_error("key cannot be empty"));
         }
 
-        let result = block_on(async { self.inner.get(key.as_bytes()).await }).map_err(map_error)?;
-
+        let result = block_on_result(async { self.inner.get(key.as_bytes()).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
     }
 
@@ -114,9 +111,8 @@ impl Reader {
             opts.dirty = dirty;
         }
 
-        let result = block_on(async { self.inner.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
-
+        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()))
     }
 
@@ -126,8 +122,7 @@ impl Reader {
             return Err(invalid_argument_error("key cannot be empty"));
         }
 
-        let result = block_on(async { self.inner.get(key.as_bytes()).await }).map_err(map_error)?;
-
+        let result = block_on_result(async { self.inner.get(key.as_bytes()).await })?;
         Ok(result.map(|b| b.to_vec()))
     }
 
@@ -140,12 +135,11 @@ impl Reader {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => self.inner.scan(start_bytes..end).await,
                 None => self.inner.scan(start_bytes..).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -196,12 +190,11 @@ impl Reader {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => self.inner.scan_with_options(start_bytes..end, &opts).await,
                 None => self.inner.scan_with_options(start_bytes.., &opts).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -209,7 +202,7 @@ impl Reader {
 
     /// Close the reader.
     pub fn close(&self) -> Result<(), Error> {
-        block_on(async { self.inner.close().await }).map_err(map_error)?;
+        block_on_result(async { self.inner.close().await })?;
         Ok(())
     }
 }

data/ext/slatedb/src/runtime.rs

@@ -1,9 +1,13 @@
+use magnus::Error;
 use once_cell::sync::OnceCell;
 use rb_sys::rb_thread_call_without_gvl;
+use slatedb::Error as SlateError;
 use std::ffi::c_void;
 use std::future::Future;
 use tokio::runtime::Runtime;
 
+use crate::errors::map_error;
+
 static RUNTIME: OnceCell<Runtime> = OnceCell::new();
 
 /// Get or initialize the shared Tokio runtime for all SlateDB operations.
@@ -22,20 +26,38 @@ fn get_runtime() -> &'static Runtime {
 
 /// Execute a future on the runtime, releasing the Ruby GVL while waiting.
 ///
-/// This is critical for thread safety - it allows other Ruby threads to run
-/// while this thread waits for I/O operations to complete. Without this,
-/// multiple Ruby threads calling SlateDB operations would deadlock.
+/// # GVL Safety
+///
+/// This function releases Ruby's Global VM Lock (GVL) while the future executes,
+/// allowing other Ruby threads to run concurrently. This means:
+///
+/// - **Do NOT call Ruby APIs** inside the future (e.g., `Ruby::get()`, creating
+///   Ruby exceptions, or calling magnus functions that require Ruby)
+/// - **Do NOT use `map_error`** or other error converters inside the async block
+/// - Return raw Rust types/errors from the future, then convert to Ruby types
+///   after `block_on` returns (when the GVL is re-acquired)
+///
+/// For futures that return `Result<T, slatedb::Error>`, use [`block_on_result`]
+/// which handles error conversion automatically.
 pub fn block_on<F, T>(future: F) -> T
 where
     F: Future<Output = T>,
 {
     let rt = get_runtime();
-
-    // Use rb_thread_call_without_gvl to release the GVL while blocking
-    // This allows other Ruby threads to execute while we wait for I/O
     without_gvl(|| rt.block_on(future))
 }
 
+/// Execute a future returning `Result<T, slatedb::Error>`, converting errors to Ruby.
+///
+/// This is a convenience wrapper around [`block_on`] that automatically converts
+/// SlateDB errors to Ruby exceptions after the GVL is re-acquired.
+pub fn block_on_result<F, T>(future: F) -> Result<T, Error>
+where
+    F: Future<Output = Result<T, SlateError>>,
+{
+    block_on(future).map_err(map_error)
+}
+
 /// Execute a closure without holding the Ruby GVL.
 ///
 /// This releases the Global VM Lock, allowing other Ruby threads to run

data/ext/slatedb/src/snapshot.rs

@@ -6,9 +6,9 @@ use magnus::{method, Error, RHash, Ruby};
 use slatedb::config::{DurabilityLevel, ReadOptions, ScanOptions};
 use slatedb::DbSnapshot;
 
-use crate::errors::{closed_error, invalid_argument_error, map_error};
+use crate::errors::{closed_error, invalid_argument_error};
 use crate::iterator::Iterator;
-use crate::runtime::block_on;
+use crate::runtime::block_on_result;
 use crate::utils::get_optional;
 
 /// Ruby wrapper for SlateDB Snapshot.
@@ -39,8 +39,7 @@ impl Snapshot {
             .as_ref()
             .ok_or_else(|| closed_error("snapshot is closed"))?;
 
-        let result = block_on(async { snapshot.get(key.as_bytes()).await }).map_err(map_error)?;
-
+        let result = block_on_result(async { snapshot.get(key.as_bytes()).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
     }
 
@@ -74,9 +73,8 @@ impl Snapshot {
             .as_ref()
             .ok_or_else(|| closed_error("snapshot is closed"))?;
 
-        let result = block_on(async { snapshot.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
-
+        let result =
+            block_on_result(async { snapshot.get_with_options(key.as_bytes(), &opts).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
     }
 
@@ -94,12 +92,11 @@ impl Snapshot {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => snapshot.scan(start_bytes..end).await,
                 None => snapshot.scan(start_bytes..).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -155,12 +152,11 @@ impl Snapshot {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => snapshot.scan_with_options(start_bytes..end, &opts).await,
                 None => snapshot.scan_with_options(start_bytes.., &opts).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))

data/ext/slatedb/src/transaction.rs

@@ -7,7 +7,7 @@ use slatedb::DBTransaction;
 
 use crate::errors::{closed_error, invalid_argument_error, map_error};
 use crate::iterator::Iterator;
-use crate::runtime::block_on;
+use crate::runtime::block_on_result;
 use crate::utils::get_optional;
 
 /// Ruby wrapper for SlateDB Transaction.
@@ -38,8 +38,7 @@ impl Transaction {
             .as_ref()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        let result = block_on(async { txn.get(key.as_bytes()).await }).map_err(map_error)?;
-
+        let result = block_on_result(async { txn.get(key.as_bytes()).await })?;
         Ok(result.map(|b| String::from_utf8_lossy(&b).to_string()))
     }
 
@@ -73,9 +72,8 @@ impl Transaction {
             .as_ref()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        let result = block_on(async { txn.get_with_options(key.as_bytes(), &opts).await })
-            .map_err(map_error)?;
-
+        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()))
     }
 
@@ -151,12 +149,11 @@ impl Transaction {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => txn.scan(start_bytes..end).await,
                 None => txn.scan(start_bytes..).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -212,12 +209,11 @@ impl Transaction {
         let start_bytes = start.into_bytes();
         let end_bytes = end_key.map(|e| e.into_bytes());
 
-        let iter = block_on(async {
-            let range = match end_bytes {
+        let iter = block_on_result(async {
+            match end_bytes {
                 Some(end) => txn.scan_with_options(start_bytes..end, &opts).await,
                 None => txn.scan_with_options(start_bytes.., &opts).await,
-            };
-            range.map_err(map_error)
+            }
         })?;
 
         Ok(Iterator::new(iter))
@@ -231,8 +227,7 @@ impl Transaction {
             .take()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        block_on(async { txn.commit().await }).map_err(map_error)?;
-
+        block_on_result(async { txn.commit().await })?;
         Ok(())
     }
 
@@ -247,8 +242,7 @@ impl Transaction {
             .take()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        block_on(async { txn.commit_with_options(&write_opts).await }).map_err(map_error)?;
-
+        block_on_result(async { txn.commit_with_options(&write_opts).await })?;
         Ok(())
     }
 

data/ext/slatedb/src/utils.rs

@@ -1,5 +1,11 @@
+use std::sync::Arc;
+
 use magnus::value::ReprValue;
 use magnus::{Error, RHash, Ruby, TryConvert};
+use object_store::aws::AmazonS3Builder;
+use object_store::ObjectStoreScheme;
+use slatedb::{Db, Error as SlateError};
+use url::Url;
 
 /// Helper to extract an optional value from an RHash
 pub fn get_optional<T: TryConvert>(hash: &RHash, key: &str) -> Result<Option<T>, Error> {
@@ -16,3 +22,37 @@ pub fn get_optional<T: TryConvert>(hash: &RHash, key: &str) -> Result<Option<T>,
         None => Ok(None),
     }
 }
+
+/// Convert an object_store error to a SlateDB error
+fn to_slate_error(e: object_store::Error) -> SlateError {
+    SlateError::unavailable(e.to_string())
+}
+
+/// Resolve an object store URL to an ObjectStore instance.
+///
+/// This function handles S3 URLs specially to ensure environment variables
+/// like AWS_ACCESS_KEY_ID are properly recognized (the default object_store
+/// registry only recognizes lowercase variants like aws_access_key_id).
+pub fn resolve_object_store(url: &str) -> Result<Arc<dyn object_store::ObjectStore>, SlateError> {
+    let parsed_url: Url = url
+        .try_into()
+        .map_err(|e: url::ParseError| SlateError::invalid(format!("invalid URL: {}", e)))?;
+
+    let (scheme, _path) =
+        ObjectStoreScheme::parse(&parsed_url).map_err(|e| to_slate_error(e.into()))?;
+
+    match scheme {
+        ObjectStoreScheme::AmazonS3 => {
+            // Use from_env() to properly handle uppercase AWS_* environment variables
+            let store = AmazonS3Builder::from_env()
+                .with_url(url)
+                .build()
+                .map_err(to_slate_error)?;
+            Ok(Arc::new(store))
+        }
+        _ => {
+            // Fall back to slatedb's default resolver for other schemes
+            Db::resolve_object_store(url)
+        }
+    }
+}

data/lib/slatedb/database.rb

@@ -2,6 +2,8 @@
 
 module SlateDb
   class Database
+    private_class_method :new
+
     class << self
       # Open a database at the given path.
       #

data/lib/slatedb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SlateDb
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slatedb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - SlateDB Contributors