slatedb 0.2.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0026c9e2a5afd6e0d7fa35c10b037791910a2438cf0bcec73c9935db557c9a85
-  data.tar.gz: 140bdf13e24d576e87165a63f31e3a0130244f36ea1278da7da5e6703347f7c5
+  metadata.gz: 5ea58f5cc108fef4066004dce3db7641d979589c6afa56023845b4e568198630
+  data.tar.gz: c5e52bded1c840e6d51ba420b673c5f03e3f9450dd78476dc129a45cab02b11b
 SHA512:
-  metadata.gz: ae8fe00e7069801bfdf8cf90ea48bfee6a60ed1413cdbc8bef5b9a083744436a0b3d3c1e46ef51c5cbd5de85bd46c6c332ec4b016ffd6482a729fa0b3a50e531
-  data.tar.gz: 5e60f6509c2eae4c948751d941f6cd7389dae8e43e241d02d559c47251b26383c6a59fcedb50133d54759d9d791a9f07079f6eed37106a386358094f2f3a5b7e
+  metadata.gz: 715e35df65d25a1487f648718ec72e593fed5e22289f47c2017aa8eac24ccda5d5df00151ec618b1d732550be2f8b6ac5d8136b9358d18c197ae11b5e437e8a9
+  data.tar.gz: 92780ae93284906f92a4e4550d885c281af32f7cd1f91642e6ca9ebbe1f114d574d20a17be3f0605b5caaaafe64e27e70f12a96b5fcc6255fd8f0e210f0fa9b1

data/README.md

@@ -8,10 +8,6 @@ Ruby bindings for [SlateDB](https://slatedb.io), a cloud-native embedded key-val
 
 These bindings are still in early development, and while SlateDB itself is used in Production, these bindings have yet to be. Contributions are welcome!
 
-### TODO
-
-- [ ] Cross-compile native extensions
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,8 +28,7 @@ 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.
+Precompiled native gems are published for common Linux and Darwin platforms. Building from source still requires a Rust toolchain.
 
 ## Usage
 
@@ -138,6 +133,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 +174,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 +222,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") }
@@ -196,6 +250,11 @@ 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|
@@ -204,6 +263,27 @@ db.transaction do |txn|
 end
 ```
 
+You can narrow a prefix scan to a sub-range using the `from:` (inclusive) and
+`to:` (exclusive) options (SlateDB >= 0.14.0). Both are key *suffixes* that are
+appended to the prefix, so they let you paginate or resume within a prefix
+without building full-key ranges by hand. The scan never escapes the prefix.
+
+```ruby
+# Keys "user:100" (inclusive) up to "user:200" (exclusive)
+db.scan_prefix("user:", from: "100", to: "200").each do |key, value|
+  puts "#{key}: #{value}"
+end
+
+# Only a lower bound: from "user:500" to the end of the prefix
+db.scan_prefix("user:", from: "500")
+
+# Only an upper bound: from the start of the prefix up to (but not including) "user:100"
+db.scan_prefix("user:", to: "100")
+
+# Sub-ranges compose with order: and work on transactions, snapshots, and readers
+db.scan_prefix("user:", from: "100", to: "200", order: :desc)
+```
+
 ### Merge Operations
 
 Merge operations allow you to combine values without reading them first, useful for counters, append-only logs, and similar patterns:
@@ -423,12 +503,33 @@ SlateDb::Reader.open("/tmp/mydb", url: "s3://bucket/path") do |reader|
   end
 end
 
-# Open at a specific checkpoint
+# Open at a specific checkpoint (pins the reader to that checkpoint's state)
 SlateDb::Reader.open("/tmp/mydb", 
                      url: "s3://bucket/path",
                      checkpoint_id: "uuid-here") do |reader|
   reader.get("key")
 end
+
+# Follow the latest state without managing a checkpoint (SlateDB >= 0.15.0).
+# This performs no object-store writes but offers no protection from garbage
+# collection, so it suits read-only or mirrored databases. By default (neither
+# checkpoint_id nor follow_latest set) the reader creates and periodically
+# refreshes its own checkpoint instead.
+SlateDb::Reader.open("/tmp/mydb",
+                     url: "s3://bucket/path",
+                     follow_latest: true) 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
@@ -527,9 +628,40 @@ Exception hierarchy:
 
 ## Requirements
 
-- Ruby 3.1+
+- Ruby 3.3+
 - Rust toolchain (for building from source)
 
+## Releasing
+
+Releases publish a generic `ruby` platform gem and **precompiled native gems**
+for six platforms (`x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`,
+`aarch64-linux-musl`, `arm64-darwin`, `x86_64-darwin`) to
+[rubygems.org](https://rubygems.org/gems/slatedb). The generic gem keeps
+RubyGems' latest-version metadata aligned; supported platforms should still
+resolve to their matching precompiled native gem.
+
+### Cutting a release
+
+The gem version comes from `lib/slatedb/version.rb`, not from the tag. Use the
+mise helper to bump, commit, tag, and push in one step (must be on `main` with a
+clean working tree):
+
+```bash
+mise run release:cut 0.4.3
+# or: mise run release:cut 0.4.3 --no-push
+```
+
+That updates `SlateDb::VERSION`, commits `Release v0.4.3`, creates tag `v0.4.3`,
+and pushes the commit + tag (unless `--no-push`). The tag triggers the release
+pipeline.
+
+The `release:verify-tag` step fails the build if the tag and
+`SlateDb::VERSION` disagree, so the tag (`v0.4.3`) must match `version.rb`
+(`0.4.3`).
+
+To exercise packaging without publishing, trigger a manual build on the
+`slatedb-rb-release` pipeline or set `DRY_RUN=true`.
+
 ## Development
 
 After checking out the repo, run:

data/ext/slatedb/Cargo.toml

@@ -11,12 +11,13 @@ name = "slatedb"
 crate-type = ["cdylib"]
 
 [dependencies]
-slatedb = "0.10"
+slatedb = "0.15.0"
 magnus = { version = "0.8.2", features = ["rb-sys"] }
-rb-sys = { version = "0.9.123", features = ["stable-api-compiled-fallback"] }
-tokio = { version = "1.47.2", features = ["rt-multi-thread", "sync"] }
-bytes = "1.11.0"
-url = "2.5.7"
-once_cell = "1.21.3"
+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.19.0"
+uuid = "1.23.1"

data/ext/slatedb/src/admin.rs

@@ -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))
         })
@@ -217,6 +230,7 @@ impl Admin {
                         Some(GarbageCollectorDirectoryOptions {
                             interval: default_opts.as_ref().and_then(|o| o.interval),
                             min_age: std::time::Duration::from_millis(ms),
+                            dry_run: default_opts.as_ref().map(|o| o.dry_run).unwrap_or(false),
                         })
                     } else {
                         default_opts
@@ -230,12 +244,17 @@ impl Admin {
                     default_opts.manifest_options,
                 ),
                 wal_options: make_dir_opts(wal_min_age, min_age, default_opts.wal_options),
+                wal_fence_options: default_opts.wal_fence_options,
                 compacted_options: make_dir_opts(
                     compacted_min_age,
                     min_age,
                     default_opts.compacted_options,
                 ),
                 compactions_options: default_opts.compactions_options,
+                detach_options: default_opts.detach_options,
+                metric_level: default_opts.metric_level,
+                boundary_files_enabled: default_opts.boundary_files_enabled,
+                object_store_max_retries: default_opts.object_store_max_retries,
             }
         };