slatedb 0.1.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c93234ef6d9251d54b90cd816983c1d073d159587ae655fbef8e4e3b433928a3
-  data.tar.gz: 0b7aa7b9137ff2228f7e4153da2daafbb235ce857b51faa8d552c55f18cb7e7a
+  metadata.gz: 9e7afb38b40ead3216b671173af52bf1a30215979f8e850dbb1e4f7dabf823f3
+  data.tar.gz: '03923c7ffdd47ba2ea9d846e98af2f66ce8fc1287e3ed3e99d21e5c27db05a8b'
 SHA512:
-  metadata.gz: 54cc3a48576fc4ca07dc6ae95a755aa6fc5dd7fa7af46eba3452f3465c74d005d9f29d06ac1cc9ddf3461d602d910d63a08f55b0d486140ed22024f3ce1e3e4e
-  data.tar.gz: 2bd1c37ca9fcfa737bd47fd3d76b136376819b573a08e044c06114f5555d5243e8b465b7bbc8cba02f3461982cc5ea1e4195fb31e53a5f0d4dcd608d1ea79f55
+  metadata.gz: d693ec11b74c8eea9722a270f48ccf8d209f21138a24dac54fbfa5d8242e23233982ea1f94aa31a667d4c0902c524213d20a9872fb6fb538685446d0efbb4fd1
+  data.tar.gz: 2e1b75894800650de82f8671bd07eefc678b6cfaaf6259245fbf854f8faaa0b8651f5c0ba1f07f4be5a8b0d85b2b54ca19177d2801a1f0f91400dde42202477a

data/README.md

@@ -138,6 +138,34 @@ db.put("key", "value", ttl: 60_000)  # expires in 60 seconds
 
 # Don't wait for durability
 db.put("key", "value", await_durable: false)
+
+# Supply an explicit sequence number (SlateDB >= 0.13.0)
+db.put("key", "value", seqnum: 42)
+```
+
+#### User-Supplied Sequence Numbers
+
+By default SlateDB assigns a monotonically increasing sequence number to every
+write. Since SlateDB 0.13.0 you can instead supply your own via `seqnum:`. The
+value must be **strictly greater** than the current maximum sequence number, or
+the write is rejected with `SlateDb::InvalidArgumentError`. This is useful when
+replaying an external log or coordinating sequence numbers across systems.
+
+```ruby
+db.put("key", "value", seqnum: 1_000)
+db.delete("old", seqnum: 1_001)
+db.merge("counter", "5", seqnum: 1_002)        # requires a merge operator
+db.write(batch, seqnum: 1_003)                 # applied across the batch
+db.batch(seqnum: 1_004) { |b| b.put("k", "v") }
+
+# The sequence number is reflected in the stored record
+db.put("key", "value", seqnum: 2_000)
+db.get_key_value("key")[:seq]  # => 2000
+
+# On a transaction it is supplied at commit time
+txn = db.begin_transaction
+txn.put("k", "v")
+txn.commit(seqnum: 3_000)
 ```
 
 #### Get Options
@@ -151,11 +179,37 @@ db.get("key", durability_filter: "remote")
 db.get("key", dirty: true)
 ```
 
+#### Key-Value Metadata
+
+SlateDB can return the full key-value record, including storage metadata:
+
+```ruby
+db.put("key", "value")
+entry = db.get_key_value("key")
+# => { key: "key", value: "value", seq: 1, create_ts: 1_765_000_000_000, expire_ts: nil }
+
+entry[:value]     # => "value"
+entry[:seq]       # SlateDB sequence number
+entry[:create_ts] # creation timestamp in milliseconds
+entry[:expire_ts] # expiration timestamp in milliseconds, or nil
+
+# Alias for the same API
+db.get_entry("key")
+
+# The same read options accepted by #get are supported
+db.get_key_value("key", durability_filter: "memory", cache_blocks: false)
+```
+
+Missing keys return `nil`, matching `#get`.
+
 #### Delete Options
 
 ```ruby
 # Don't wait for durability
 db.delete("key", await_durable: false)
+
+# Supply an explicit sequence number (SlateDB >= 0.13.0)
+db.delete("key", seqnum: 42)
 ```
 
 ### Scanning
@@ -173,6 +227,11 @@ db.scan("a", "z").each do |key, value|
   puts "#{key}: #{value}"
 end
 
+# Scan in descending key order
+db.scan("a", "z", order: :desc).each do |key, value|
+  puts "#{key}: #{value}"
+end
+
 # Use Enumerable methods
 keys = db.scan("user:").map { |k, v| k }
 users = db.scan("user:").select { |k, v| v.include?("active") }
@@ -181,6 +240,110 @@ users = db.scan("user:").select { |k, v| v.include?("active") }
 all_entries = db.scan("").to_a
 ```
 
+#### Prefix Scanning
+
+Scan all keys with a given prefix using `scan_prefix`:
+
+```ruby
+# Scan all keys starting with "user:"
+db.scan_prefix("user:").each do |key, value|
+  puts "#{key}: #{value}"
+end
+
+# Block form
+db.scan_prefix("order:") do |key, value|
+  puts "#{key}: #{value}"
+end
+
+# Prefix scans can also run in descending key order
+db.scan_prefix("user:", order: :desc).each do |key, value|
+  puts "#{key}: #{value}"
+end
+
+# Works with transactions, snapshots, and readers too
+db.transaction do |txn|
+  txn.scan_prefix("item:").each do |k, v|
+    puts "#{k}: #{v}"
+  end
+end
+```
+
+### Merge Operations
+
+Merge operations allow you to combine values without reading them first, useful for counters, append-only logs, and similar patterns:
+
+```ruby
+# Open with a built-in merge operator
+SlateDb::Database.open("/tmp/mydb", merge_operator: :string_concat) do |db|
+  # Merge appends to existing values (or creates if key doesn't exist)
+  db.merge("log", "line1\n")
+  db.merge("log", "line2\n")
+  db.merge("log", "line3\n")
+
+  db.get("log")  # => "line1\nline2\nline3\n"
+end
+
+# Merge with options
+db.merge("key", "value", ttl: 60_000, await_durable: false)
+
+# Works in transactions and batches
+db.transaction do |txn|
+  txn.merge("counter", "1")
+end
+
+db.batch do |b|
+  b.merge("key", "a")
+   .merge("key", "b")
+end
+```
+
+#### Custom Merge Operators
+
+You can provide a Ruby Proc/lambda as a custom merge operator:
+
+```ruby
+# Counter merge operator (adds numbers)
+counter_merge = ->(key, existing, new_value) {
+  existing_num = existing ? existing.to_i : 0
+  (existing_num + new_value.to_i).to_s
+}
+
+SlateDb::Database.open("/tmp/mydb", merge_operator: counter_merge) do |db|
+  db.merge("visits", "1")
+  db.merge("visits", "1")
+  db.merge("visits", "1")
+
+  db.get("visits")  # => "3"
+end
+
+# Max value merge operator
+max_merge = ->(key, existing, new_value) {
+  existing_num = existing ? existing.to_i : 0
+  new_num = new_value.to_i
+  [existing_num, new_num].max.to_s
+}
+
+SlateDb::Database.open("/tmp/mydb", merge_operator: max_merge) do |db|
+  db.merge("high_score", "100")
+  db.merge("high_score", "250")
+  db.merge("high_score", "150")
+
+  db.get("high_score")  # => "250"
+end
+```
+
+The proc receives three arguments:
+- `key` - The key being merged
+- `existing` - The existing value (nil if no value exists)
+- `new_value` - The new merge operand
+
+**Note:** Custom Proc merge operators work best with direct `db.merge()` calls. When used with transactions or batches, some merge operations may be processed on background threads and fall back to string concatenation.
+
+#### Available Merge Operators
+
+- `:string_concat` (or `:concat`) - Concatenates byte values (built-in)
+- Any `Proc` or `lambda` - Custom merge logic
+
 ### Write Batches
 
 Perform multiple writes atomically:
@@ -231,18 +394,60 @@ Transaction operations:
 db.transaction do |txn|
   # Read
   value = txn.get("key")
-  
+
   # Write
   txn.put("key", "value")
   txn.put("expiring", "data", ttl: 30_000)
-  
+
   # Delete
   txn.delete("old_key")
-  
+
   # Scan
   txn.scan("prefix:").each do |k, v|
     puts "#{k}: #{v}"
   end
+
+  # Scan with prefix
+  txn.scan_prefix("user:").each do |k, v|
+    puts "#{k}: #{v}"
+  end
+end
+```
+
+#### Explicit Read Tracking
+
+In serializable transactions, use `mark_read` to explicitly track keys for conflict detection without actually reading them:
+
+```ruby
+db.transaction(isolation: :serializable) do |txn|
+  # Mark keys as read for conflict detection
+  txn.mark_read(["key1", "key2", "key3"])
+
+  # Now if another transaction modifies key1/key2/key3,
+  # this transaction will fail on commit
+  txn.put("result", "computed_value")
+end
+```
+
+### Checkpoints
+
+Create durable checkpoints for backup or read replica purposes:
+
+```ruby
+SlateDb::Database.open("/tmp/mydb", url: "file:///tmp/mydb") do |db|
+  db.put("key", "value")
+  db.flush
+
+  # Create a checkpoint
+  checkpoint = db.create_checkpoint
+  puts "Checkpoint ID: #{checkpoint[:id]}"
+  puts "Manifest ID: #{checkpoint[:manifest_id]}"
+
+  # Create a named checkpoint with lifetime
+  checkpoint = db.create_checkpoint(
+    name: "before-migration",
+    lifetime: 3_600_000  # 1 hour in milliseconds
+  )
 end
 ```
 
@@ -288,6 +493,16 @@ SlateDb::Reader.open("/tmp/mydb",
                      checkpoint_id: "uuid-here") do |reader|
   reader.get("key")
 end
+
+# Enable the reader's on-disk cache and cap its open file handles
+# (max_open_file_handles, added in SlateDB 0.13.0, only takes effect when
+# cache_root is set, since that is what enables the cached object store).
+SlateDb::Reader.open("/tmp/mydb",
+                     url: "s3://bucket/path",
+                     cache_root: "/var/cache/slatedb",
+                     max_open_file_handles: 256) do |reader|
+  reader.get("key")
+end
 ```
 
 ### Admin Operations
@@ -386,7 +601,7 @@ Exception hierarchy:
 
 ## Requirements
 
-- Ruby 3.1+
+- Ruby 3.3+
 - Rust toolchain (for building from source)
 
 ## Development

data/ext/slatedb/Cargo.toml

@@ -11,13 +11,13 @@ name = "slatedb"
 crate-type = ["cdylib"]
 
 [dependencies]
-slatedb = "0.9"
-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 = { version = "0.12", features = ["aws"] }
-url = "2"
-once_cell = "1"
-log = "0.4"
-uuid = "1"
+slatedb = "0.13.1"
+magnus = { version = "0.8.2", features = ["rb-sys"] }
+rb-sys = { version = "0.9.128", features = ["stable-api-compiled-fallback"] }
+tokio = { version = "1.52.3", features = ["rt-multi-thread", "sync"] }
+bytes = "1.11.1"
+serde_json = "1.0.145"
+url = "2.5.8"
+once_cell = "1.21.4"
+log = "0.4.29"
+uuid = "1.23.1"

data/ext/slatedb/src/admin.rs

@@ -25,10 +25,10 @@ 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 object_store: Arc<dyn object_store::ObjectStore> = if let Some(ref url) = url {
+        let object_store: Arc<dyn slatedb::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())
+            Arc::new(slatedb::object_store::memory::InMemory::new())
         };
 
         let admin = AdminBuilder::new(path, object_store).build();
@@ -43,10 +43,18 @@ impl Admin {
     /// # Returns
     /// JSON string of the manifest, or None if no manifests exist.
     pub fn read_manifest(&self, id: Option<u64>) -> Result<Option<String>, Error> {
-        block_on(async { self.inner.read_manifest(id).await }).map_err(|e| {
+        let manifest = block_on(async { self.inner.read_manifest(id).await }).map_err(|e| {
             let ruby = Ruby::get().expect("Ruby runtime not available");
             Error::new(ruby.exception_runtime_error(), format!("{}", e))
-        })
+        })?;
+
+        match manifest {
+            Some(manifest) => Ok(Some(serde_json::to_string(&manifest).map_err(|e| {
+                let ruby = Ruby::get().expect("Ruby runtime not available");
+                Error::new(ruby.exception_runtime_error(), format!("{}", e))
+            })?)),
+            None => Ok(None),
+        }
     }
 
     /// List manifests within an optional [start, end) range as JSON.
@@ -65,7 +73,12 @@ impl Admin {
             (None, None) => 0..u64::MAX,
         };
 
-        block_on(async { self.inner.list_manifests(range).await }).map_err(|e| {
+        let manifests = block_on(async { self.inner.list_manifests(range).await }).map_err(|e| {
+            let ruby = Ruby::get().expect("Ruby runtime not available");
+            Error::new(ruby.exception_runtime_error(), format!("{}", e))
+        })?;
+
+        serde_json::to_string(&manifests).map_err(|e| {
             let ruby = Ruby::get().expect("Ruby runtime not available");
             Error::new(ruby.exception_runtime_error(), format!("{}", e))
         })
@@ -235,6 +248,8 @@ impl Admin {
                     min_age,
                     default_opts.compacted_options,
                 ),
+                compactions_options: default_opts.compactions_options,
+                detach_options: default_opts.detach_options,
             }
         };