slatedb 0.1.1 → 0.3.1

data/lib/slatedb/database.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SlateDb
-  class Database
+  class Database # rubocop:disable Metrics/ClassLength
     private_class_method :new
 
     class << self
@@ -9,6 +9,9 @@ module SlateDb
       #
       # @param path [String] The path identifier for the database
       # @param url [String, nil] Optional object store URL (e.g., "s3://bucket/path")
+      # @param merge_operator [Symbol, String, Proc, nil] Optional merge operator.
+      #   Can be a symbol/string ("string_concat" or "concat") or a Proc/lambda
+      #   that takes (key, existing_value, new_value) and returns the merged value.
       # @yield [db] If a block is given, yields the database and ensures it's closed
       # @return [Database] The opened database (or block result if block given)
       #
@@ -25,8 +28,29 @@ module SlateDb
       # @example Open with S3 backend
       #   db = SlateDb::Database.open("/tmp/mydb", url: "s3://mybucket/path")
       #
-      def open(path, url: nil)
-        db = _open(path, url)
+      # @example Open with a custom merge operator (Proc)
+      #   # Custom merge that adds numbers
+      #   db = SlateDb::Database.open("/tmp/mydb", merge_operator: ->(key, existing, new_val) {
+      #     existing_num = existing ? existing.to_i : 0
+      #     (existing_num + new_val.to_i).to_s
+      #   })
+      #   db.merge("counter", "5")
+      #   db.merge("counter", "3")
+      #   db.get("counter") # => "8"
+      #
+      def open(path, url: nil, merge_operator: nil)
+        opts = {}
+
+        case merge_operator
+        when Symbol, String
+          opts[:merge_operator] = merge_operator.to_s
+        when Proc
+          # Store the proc to prevent GC and pass to Rust
+          @_merge_operator_proc = merge_operator
+          opts[:merge_operator_proc] = merge_operator
+        end
+
+        db = _open(path, url, opts)
 
         if block_given?
           begin
@@ -71,12 +95,44 @@ module SlateDb
       end
     end
 
+    # Get a key-value pair with SlateDB metadata.
+    #
+    # @param key [String] The key to look up
+    # @param durability_filter [String, nil] Filter by durability level ("remote" or "memory")
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @return [Hash, nil] A hash with :key, :value, :seq, :create_ts, and :expire_ts, or nil if not found
+    #
+    # @example Inspect metadata
+    #   entry = db.get_key_value("mykey")
+    #   entry[:value] # => "myvalue"
+    #   entry[:seq]   # => sequence number
+    #
+    def get_key_value(key, durability_filter: nil, dirty: nil, cache_blocks: nil)
+      opts = {}
+      opts[:durability_filter] = durability_filter.to_s if durability_filter
+      opts[:dirty] = dirty unless dirty.nil?
+      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
+
+      if opts.empty?
+        _get_key_value(key)
+      else
+        _get_key_value_with_options(key, opts)
+      end
+    end
+
+    alias get_entry get_key_value
+
     # Store a key-value pair.
     #
     # @param key [String] The key to store
     # @param value [String] The value to store
     # @param ttl [Integer, nil] Time-to-live in milliseconds
     # @param await_durable [Boolean] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number for this write.
+    #   When provided (and non-zero), it is used instead of the internally
+    #   generated sequence number. It must be strictly greater than the current
+    #   maximum sequence number or the write fails. (Requires SlateDB >= 0.13.0)
     # @return [void]
     #
     # @example Basic put
@@ -88,10 +144,14 @@ module SlateDb
     # @example Put without waiting for durability
     #   db.put("mykey", "myvalue", await_durable: false)
     #
-    def put(key, value, ttl: nil, await_durable: nil)
+    # @example Put with an explicit sequence number
+    #   db.put("mykey", "myvalue", seqnum: 42)
+    #
+    def put(key, value, ttl: nil, await_durable: nil, seqnum: nil)
       opts = {}
       opts[:ttl] = ttl if ttl
       opts[:await_durable] = await_durable unless await_durable.nil?
+      opts[:seqnum] = seqnum if seqnum
 
       if opts.empty?
         _put(key, value)
@@ -104,6 +164,8 @@ module SlateDb
     #
     # @param key [String] The key to delete
     # @param await_durable [Boolean] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number for this write.
+    #   See {#put} for semantics. (Requires SlateDB >= 0.13.0)
     # @return [void]
     #
     # @example Basic delete
@@ -112,11 +174,15 @@ module SlateDb
     # @example Delete without waiting for durability
     #   db.delete("mykey", await_durable: false)
     #
-    def delete(key, await_durable: nil)
-      if await_durable.nil?
+    def delete(key, await_durable: nil, seqnum: nil)
+      opts = {}
+      opts[:await_durable] = await_durable unless await_durable.nil?
+      opts[:seqnum] = seqnum if seqnum
+
+      if opts.empty?
         _delete(key)
       else
-        _delete_with_options(key, { await_durable: await_durable })
+        _delete_with_options(key, opts)
       end
     end
 
@@ -129,6 +195,7 @@ module SlateDb
     # @param read_ahead_bytes [Integer, nil] Number of bytes to read ahead
     # @param cache_blocks [Boolean, nil] Whether to cache blocks
     # @param max_fetch_tasks [Integer, nil] Maximum number of fetch tasks
+    # @param order [Symbol, String, nil] Iteration order (:asc/:ascending or :desc/:descending)
     # @return [Iterator] An iterator over key-value pairs
     #
     # @example Basic scan
@@ -147,13 +214,15 @@ module SlateDb
     #   end
     #
     def scan(start_key, end_key = nil, durability_filter: nil, dirty: nil,
-             read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, &)
-      opts = {}
-      opts[:durability_filter] = durability_filter.to_s if durability_filter
-      opts[:dirty] = dirty unless dirty.nil?
-      opts[:read_ahead_bytes] = read_ahead_bytes if read_ahead_bytes
-      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
-      opts[:max_fetch_tasks] = max_fetch_tasks if max_fetch_tasks
+             read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, order: nil, &)
+      opts = scan_options(
+        durability_filter: durability_filter,
+        dirty: dirty,
+        read_ahead_bytes: read_ahead_bytes,
+        cache_blocks: cache_blocks,
+        max_fetch_tasks: max_fetch_tasks,
+        order: order
+      )
 
       iter = if opts.empty?
                _scan(start_key, end_key)
@@ -168,10 +237,66 @@ module SlateDb
       end
     end
 
+    # Scan all keys with a given prefix.
+    #
+    # @param prefix [String] The key prefix to scan
+    # @param durability_filter [String, nil] Filter by durability level ("remote" or "memory")
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param read_ahead_bytes [Integer, nil] Number of bytes to read ahead
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @param max_fetch_tasks [Integer, nil] Maximum number of fetch tasks
+    # @param order [Symbol, String, nil] Iteration order (:asc/:ascending or :desc/:descending)
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    # @example Scan all user keys
+    #   db.scan_prefix("user:") do |key, value|
+    #     puts "#{key}: #{value}"
+    #   end
+    #
+    def scan_prefix(prefix, durability_filter: nil, dirty: nil,
+                    read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, order: nil, &)
+      opts = scan_options(
+        durability_filter: durability_filter,
+        dirty: dirty,
+        read_ahead_bytes: read_ahead_bytes,
+        cache_blocks: cache_blocks,
+        max_fetch_tasks: max_fetch_tasks,
+        order: order
+      )
+
+      iter = if opts.empty?
+               _scan_prefix(prefix)
+             else
+               _scan_prefix_with_options(prefix, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        iter
+      end
+    end
+
+    def scan_options(durability_filter:, dirty:, read_ahead_bytes:, cache_blocks:,
+                     max_fetch_tasks:, order:)
+      opts = {}
+      opts[:durability_filter] = durability_filter.to_s if durability_filter
+      opts[:dirty] = dirty unless dirty.nil?
+      opts[:read_ahead_bytes] = read_ahead_bytes if read_ahead_bytes
+      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
+      opts[:max_fetch_tasks] = max_fetch_tasks if max_fetch_tasks
+      opts[:order] = order.to_s if order
+      opts
+    end
+
+    private :scan_options
+
     # Write a batch of operations atomically.
     #
     # @param batch [WriteBatch] The batch to write
     # @param await_durable [Boolean] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number applied to the
+    #   batch. See {#put} for semantics. (Requires SlateDB >= 0.13.0)
     # @return [void]
     #
     # @example Write a batch
@@ -187,17 +312,51 @@ module SlateDb
     #     b.put("key2", "value2")
     #   end
     #
-    def write(batch, await_durable: nil)
-      if await_durable.nil?
+    def write(batch, await_durable: nil, seqnum: nil)
+      opts = {}
+      opts[:await_durable] = await_durable unless await_durable.nil?
+      opts[:seqnum] = seqnum if seqnum
+
+      if opts.empty?
         _write(batch)
       else
-        _write_with_options(batch, { await_durable: await_durable })
+        _write_with_options(batch, opts)
+      end
+    end
+
+    # Merge a value into the database.
+    #
+    # @param key [String] The key to merge into
+    # @param value [String] The merge operand to apply
+    # @param ttl [Integer, nil] Time-to-live in milliseconds
+    # @param await_durable [Boolean] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number for this write.
+    #   See {#put} for semantics. (Requires SlateDB >= 0.13.0)
+    # @return [void]
+    #
+    # @example Merge with string concatenation operator
+    #   db = SlateDb::Database.open("/tmp/mydb", merge_operator: :string_concat)
+    #   db.merge("key", "part1")
+    #   db.merge("key", "part2")
+    #
+    def merge(key, value, ttl: nil, await_durable: nil, seqnum: nil)
+      opts = {}
+      opts[:ttl] = ttl if ttl
+      opts[:await_durable] = await_durable unless await_durable.nil?
+      opts[:seqnum] = seqnum if seqnum
+
+      if opts.empty?
+        _merge(key, value)
+      else
+        _merge_with_options(key, value, opts)
       end
     end
 
     # Create and write a batch using a block.
     #
     # @param await_durable [Boolean] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number applied to the
+    #   batch. See {#put} for semantics. (Requires SlateDB >= 0.13.0)
     # @yield [batch] Yields a WriteBatch to the block
     # @return [void]
     #
@@ -208,10 +367,10 @@ module SlateDb
     #     b.delete("old_key")
     #   end
     #
-    def batch(await_durable: nil)
+    def batch(await_durable: nil, seqnum: nil)
       b = WriteBatch.new
       yield b
-      write(b, await_durable: await_durable)
+      write(b, await_durable: await_durable, seqnum: seqnum)
     end
 
     # Begin a new transaction.
@@ -308,5 +467,32 @@ module SlateDb
         snap
       end
     end
+
+    # Create a checkpoint of the database.
+    #
+    # @param lifetime [Integer, nil] Checkpoint lifetime in milliseconds
+    # @param name [String, nil] Optional name for the checkpoint
+    # @return [Hash] Hash with :id (UUID string) and :manifest_id (integer)
+    #
+    # @example Create a named checkpoint
+    #   checkpoint = db.create_checkpoint(name: "before-migration")
+    #   puts "Checkpoint ID: #{checkpoint[:id]}"
+    #
+    # @example Create a checkpoint with lifetime
+    #   checkpoint = db.create_checkpoint(lifetime: 3600_000) # 1 hour
+    #
+    def create_checkpoint(lifetime: nil, name: nil)
+      opts = {}
+      opts[:lifetime] = lifetime if lifetime
+      opts[:name] = name if name
+      _create_checkpoint(opts)
+    end
+
+    # Get database metrics registry.
+    #
+    # @return [Metrics] Metrics registry
+    def metrics
+      _metrics
+    end
   end
 end

data/lib/slatedb/metrics.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class Metrics
+    # Get a metric value by name.
+    #
+    # @param name [String] Metric name
+    # @return [Integer, nil] Current value or nil if not found
+    def [](name)
+      get(name)
+    end
+
+    # Convert all metrics to a hash.
+    #
+    # @return [Hash] Map of metric name to value
+    def to_h
+      names.to_h { |metric_name| [metric_name, get(metric_name)] }
+    end
+  end
+end

data/lib/slatedb/reader.rb

@@ -11,6 +11,14 @@ module SlateDb
       # @param manifest_poll_interval [Integer, nil] Poll interval in milliseconds
       # @param checkpoint_lifetime [Integer, nil] Checkpoint lifetime in milliseconds
       # @param max_memtable_bytes [Integer, nil] Maximum memtable size in bytes
+      # @param cache_root [String, nil] Root folder for the reader's local on-disk
+      #   object-store cache. Setting this enables the cached object store; when it is
+      #   not set the cache (and `max_open_file_handles`) has no effect.
+      # @param max_open_file_handles [Integer, nil] Maximum number of file handles to keep
+      #   open in the reader's file-handle cache. When the limit is reached, the least
+      #   recently used handle is closed (default: 1000). Only takes effect when
+      #   `cache_root` is set. (Requires SlateDB >= 0.13.0)
+      # @param merge_operator [Symbol, String, nil] Optional merge operator ("string_concat" or "concat")
       # @yield [reader] If a block is given, yields the reader and ensures it's closed
       # @return [Reader] The opened reader (or block result if block given)
       #
@@ -27,13 +35,22 @@ module SlateDb
       # @example Open at a specific checkpoint
       #   reader = SlateDb::Reader.open("/tmp/mydb", checkpoint_id: "uuid-here")
       #
+      # @example Enable the on-disk cache and cap its open file handles
+      #   reader = SlateDb::Reader.open("/tmp/mydb",
+      #                                 cache_root: "/var/cache/slatedb",
+      #                                 max_open_file_handles: 256)
+      #
       def open(path, url: nil, checkpoint_id: nil,
                manifest_poll_interval: nil, checkpoint_lifetime: nil,
-               max_memtable_bytes: nil)
+               max_memtable_bytes: nil, cache_root: nil, max_open_file_handles: nil,
+               merge_operator: nil)
         opts = {}
         opts[:manifest_poll_interval] = manifest_poll_interval if manifest_poll_interval
         opts[:checkpoint_lifetime] = checkpoint_lifetime if checkpoint_lifetime
         opts[:max_memtable_bytes] = max_memtable_bytes if max_memtable_bytes
+        opts[:cache_root] = cache_root if cache_root
+        opts[:max_open_file_handles] = max_open_file_handles if max_open_file_handles
+        opts[:merge_operator] = merge_operator.to_s if merge_operator
 
         reader = _open(path, url, checkpoint_id, opts)
 
@@ -101,5 +118,37 @@ module SlateDb
         iter
       end
     end
+
+    # Scan all keys with a given prefix.
+    #
+    # @param prefix [String] The key prefix to scan
+    # @param durability_filter [String, nil] Filter by durability level
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param read_ahead_bytes [Integer, nil] Number of bytes to read ahead
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @param max_fetch_tasks [Integer, nil] Maximum number of fetch tasks
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    def scan_prefix(prefix, durability_filter: nil, dirty: nil,
+                    read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, &)
+      opts = {}
+      opts[:durability_filter] = durability_filter.to_s if durability_filter
+      opts[:dirty] = dirty unless dirty.nil?
+      opts[:read_ahead_bytes] = read_ahead_bytes if read_ahead_bytes
+      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
+      opts[:max_fetch_tasks] = max_fetch_tasks if max_fetch_tasks
+
+      iter = if opts.empty?
+               _scan_prefix(prefix)
+             else
+               _scan_prefix_with_options(prefix, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        iter
+      end
+    end
   end
 end

data/lib/slatedb/snapshot.rb

@@ -50,5 +50,37 @@ module SlateDb
         iter
       end
     end
+
+    # Scan all keys with a given prefix from the snapshot.
+    #
+    # @param prefix [String] The key prefix to scan
+    # @param durability_filter [String, nil] Filter by durability level
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param read_ahead_bytes [Integer, nil] Number of bytes to read ahead
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @param max_fetch_tasks [Integer, nil] Maximum number of fetch tasks
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    def scan_prefix(prefix, durability_filter: nil, dirty: nil,
+                    read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, &)
+      opts = {}
+      opts[:durability_filter] = durability_filter.to_s if durability_filter
+      opts[:dirty] = dirty unless dirty.nil?
+      opts[:read_ahead_bytes] = read_ahead_bytes if read_ahead_bytes
+      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
+      opts[:max_fetch_tasks] = max_fetch_tasks if max_fetch_tasks
+
+      iter = if opts.empty?
+               _scan_prefix(prefix)
+             else
+               _scan_prefix_with_options(prefix, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        iter
+      end
+    end
   end
 end

data/lib/slatedb/transaction.rb

@@ -47,6 +47,21 @@ module SlateDb
       _delete(key)
     end
 
+    # Merge a value within the transaction.
+    #
+    # @param key [String] The key to merge into
+    # @param value [String] The merge operand to apply
+    # @param ttl [Integer, nil] Time-to-live in milliseconds
+    # @return [void]
+    #
+    def merge(key, value, ttl: nil)
+      if ttl
+        _merge_with_options(key, value, { ttl: ttl })
+      else
+        _merge(key, value)
+      end
+    end
+
     # Scan a range of keys within the transaction.
     #
     # @param start_key [String] The start key (inclusive)
@@ -74,5 +89,86 @@ module SlateDb
         iter
       end
     end
+
+    # Scan all keys with a given prefix within the transaction.
+    #
+    # @param prefix [String] The key prefix to scan
+    # @param durability_filter [String, nil] Filter by durability level
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param read_ahead_bytes [Integer, nil] Number of bytes to read ahead
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @param max_fetch_tasks [Integer, nil] Maximum number of fetch tasks
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    def scan_prefix(prefix, durability_filter: nil, dirty: nil,
+                    read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil, &)
+      opts = {}
+      opts[:durability_filter] = durability_filter.to_s if durability_filter
+      opts[:dirty] = dirty unless dirty.nil?
+      opts[:read_ahead_bytes] = read_ahead_bytes if read_ahead_bytes
+      opts[:cache_blocks] = cache_blocks unless cache_blocks.nil?
+      opts[:max_fetch_tasks] = max_fetch_tasks if max_fetch_tasks
+
+      iter = if opts.empty?
+               _scan_prefix(prefix)
+             else
+               _scan_prefix_with_options(prefix, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        iter
+      end
+    end
+
+    # Mark keys as read for conflict detection.
+    #
+    # This explicitly tracks reads for conflict checking in serializable isolation,
+    # allowing selective read-write conflict detection even when keys weren't
+    # actually read via get().
+    #
+    # @param keys [Array<String>] The keys to mark as read
+    # @return [void]
+    #
+    # @example Mark keys for conflict detection
+    #   db.transaction(isolation: :serializable) do |txn|
+    #     txn.mark_read(["key1", "key2"])
+    #     # These keys will now be checked for conflicts on commit
+    #     txn.put("key3", "value")
+    #   end
+    #
+    def mark_read(keys)
+      _mark_read(Array(keys))
+    end
+
+    # Commit the transaction.
+    #
+    # @param await_durable [Boolean, nil] Whether to wait for durability (default: true)
+    # @param seqnum [Integer, nil] User-supplied sequence number for the commit.
+    #   When provided (and non-zero), it is used instead of the internally
+    #   generated sequence number and must be strictly greater than the current
+    #   maximum sequence number. (Requires SlateDB >= 0.13.0)
+    # @return [void]
+    #
+    # @example Commit a transaction
+    #   txn = db.begin_transaction
+    #   txn.put("key", "value")
+    #   txn.commit
+    #
+    # @example Commit with an explicit sequence number
+    #   txn.commit(seqnum: 99)
+    #
+    def commit(await_durable: nil, seqnum: nil)
+      opts = {}
+      opts[:await_durable] = await_durable unless await_durable.nil?
+      opts[:seqnum] = seqnum if seqnum
+
+      if opts.empty?
+        _commit
+      else
+        _commit_with_options(opts)
+      end
+    end
   end
 end

data/lib/slatedb/version.rb

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

data/lib/slatedb/write_batch.rb

@@ -34,5 +34,25 @@ module SlateDb
       _delete(key)
       self
     end
+
+    # Add a merge operation to the batch.
+    #
+    # @param key [String] The key to merge into
+    # @param value [String] The merge operand to apply
+    # @param ttl [Integer, nil] Time-to-live in milliseconds
+    # @return [self] Returns self for method chaining
+    #
+    # @example
+    #   batch.merge("key", "part1")
+    #   batch.merge("key", "part2", ttl: 30_000)
+    #
+    def merge(key, value, ttl: nil)
+      if ttl
+        _merge_with_options(key, value, { ttl: ttl })
+      else
+        _merge(key, value)
+      end
+      self
+    end
   end
 end

data/lib/slatedb.rb

@@ -18,3 +18,4 @@ require_relative "slatedb/transaction"
 require_relative "slatedb/snapshot"
 require_relative "slatedb/reader"
 require_relative "slatedb/admin"
+require_relative "slatedb/metrics"