slatedb 0.3.2.beta.3-aarch64-linux

data/lib/slatedb/reader.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class Reader
+    class << self
+      # Open a read-only reader at the given path.
+      #
+      # @param path [String] The path identifier for the database
+      # @param url [String, nil] Optional object store URL
+      # @param checkpoint_id [String, nil] Optional checkpoint UUID to read at
+      # @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)
+      #
+      # @example Open a reader
+      #   reader = SlateDb::Reader.open("/tmp/mydb")
+      #   value = reader.get("key")
+      #   reader.close
+      #
+      # @example Open with block (auto-close)
+      #   SlateDb::Reader.open("/tmp/mydb") do |reader|
+      #     reader.get("key")
+      #   end # automatically closed
+      #
+      # @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, 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)
+
+        if block_given?
+          begin
+            yield reader
+          ensure
+            begin
+              reader.close
+            rescue StandardError
+              nil
+            end
+          end
+        else
+          reader
+        end
+      end
+    end
+
+    # Get a value by key.
+    #
+    # @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 [String, nil] The value, or nil if not found
+    #
+    def get(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)
+      else
+        _get_with_options(key, opts)
+      end
+    end
+
+    # Scan a range of keys.
+    #
+    # @param start_key [String] The start key (inclusive)
+    # @param end_key [String, nil] The end key (exclusive)
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    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
+
+      iter = if opts.empty?
+               _scan(start_key, end_key)
+             else
+               _scan_with_options(start_key, end_key, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class Snapshot
+    # Get a value by key from the snapshot.
+    #
+    # @param key [String] The key to look up
+    # @param durability_filter [String, nil] Filter by durability level
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @return [String, nil] The value, or nil if not found
+    #
+    def get(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)
+      else
+        _get_with_options(key, opts)
+      end
+    end
+
+    # Scan a range of keys from the snapshot.
+    #
+    # @param start_key [String] The start key (inclusive)
+    # @param end_key [String, nil] The end key (exclusive)
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    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
+
+      iter = if opts.empty?
+               _scan(start_key, end_key)
+             else
+               _scan_with_options(start_key, end_key, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class Transaction
+    # Get a value by key within the transaction.
+    #
+    # @param key [String] The key to look up
+    # @param durability_filter [String, nil] Filter by durability level
+    # @param dirty [Boolean, nil] Whether to include uncommitted data
+    # @param cache_blocks [Boolean, nil] Whether to cache blocks
+    # @return [String, nil] The value, or nil if not found
+    #
+    def get(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)
+      else
+        _get_with_options(key, opts)
+      end
+    end
+
+    # Store a key-value pair within the transaction.
+    #
+    # @param key [String] The key to store
+    # @param value [String] The value to store
+    # @param ttl [Integer, nil] Time-to-live in milliseconds
+    # @return [void]
+    #
+    def put(key, value, ttl: nil)
+      if ttl
+        _put_with_options(key, value, { ttl: ttl })
+      else
+        _put(key, value)
+      end
+    end
+
+    # Delete a key within the transaction.
+    #
+    # @param key [String] The key to delete
+    # @return [void]
+    #
+    def delete(key)
+      _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)
+    # @param end_key [String, nil] The end key (exclusive)
+    # @return [Iterator] An iterator over key-value pairs
+    #
+    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
+
+      iter = if opts.empty?
+               _scan(start_key, end_key)
+             else
+               _scan_with_options(start_key, end_key, opts)
+             end
+
+      if block_given?
+        iter.each(&)
+      else
+        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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SlateDb
+  VERSION = "0.3.2.beta.3"
+end

data/lib/slatedb/write_batch.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SlateDb
+  class WriteBatch
+    # Add a put operation to the batch.
+    #
+    # @param key [String] The key to store
+    # @param value [String] The value to store
+    # @param ttl [Integer, nil] Time-to-live in milliseconds
+    # @return [self] Returns self for method chaining
+    #
+    # @example
+    #   batch.put("key", "value")
+    #   batch.put("key2", "value2", ttl: 60_000)
+    #
+    def put(key, value, ttl: nil)
+      if ttl
+        _put_with_options(key, value, { ttl: ttl })
+      else
+        _put(key, value)
+      end
+      self
+    end
+
+    # Add a delete operation to the batch.
+    #
+    # @param key [String] The key to delete
+    # @return [self] Returns self for method chaining
+    #
+    # @example
+    #   batch.delete("key")
+    #
+    def delete(key)
+      _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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "slatedb/version"
+
+# Load the native extension
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "slatedb/#{Regexp.last_match(1)}/slatedb"
+rescue LoadError
+  require "slatedb/slatedb"
+end
+
+# Load Ruby class extensions
+require_relative "slatedb/database"
+require_relative "slatedb/iterator"
+require_relative "slatedb/write_batch"
+require_relative "slatedb/transaction"
+require_relative "slatedb/snapshot"
+require_relative "slatedb/reader"
+require_relative "slatedb/admin"
+require_relative "slatedb/metrics"

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: slatedb
+version: !ruby/object:Gem::Version
+  version: 0.3.2.beta.3
+platform: aarch64-linux
+authors:
+- SlateDB Contributors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+description: A cloud-native embedded key-value store built on object storage
+email:
+- slatedb@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/slatedb.rb
+- lib/slatedb/3.3/slatedb.so
+- lib/slatedb/3.4/slatedb.so
+- lib/slatedb/4.0/slatedb.so
+- lib/slatedb/admin.rb
+- lib/slatedb/database.rb
+- lib/slatedb/iterator.rb
+- lib/slatedb/metrics.rb
+- lib/slatedb/reader.rb
+- lib/slatedb/snapshot.rb
+- lib/slatedb/transaction.rb
+- lib/slatedb/version.rb
+- lib/slatedb/write_batch.rb
+homepage: https://github.com/catkins/slatedb-rb
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/catkins/slatedb-rb
+  source_code_uri: https://github.com/catkins/slatedb-rb
+  changelog_uri: https://github.com/catkins/slatedb-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for SlateDB
+test_files: []