Class: SlateDb::Database

Inherits:
Object
  • Object
show all
Defined in:
lib/slatedb/database.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.open(path, url: nil) {|db| ... } ⇒ Database

Open a database at the given path.

Examples:

Open a database

db = SlateDb::Database.open("/tmp/mydb")
db.put("key", "value")
db.close

Open with block (auto-close)

SlateDb::Database.open("/tmp/mydb") do |db|
  db.put("key", "value")
end # automatically closed

Open with S3 backend

db = SlateDb::Database.open("/tmp/mydb", url: "s3://mybucket/path")

Parameters:

  • path (String) —

    The path identifier for the database

  • url (String, nil) (defaults to: nil) —

    Optional object store URL (e.g., “s3://bucket/path”)

Yields:

  • (db) —

    If a block is given, yields the database and ensures it’s closed

Returns:

  • (Database) —

    The opened database (or block result if block given)



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/slatedb/database.rb', line 28

def open(path, url: nil)
  db = _open(path, url)

  if block_given?
    begin
      yield db
    ensure
      begin
        db.close
      rescue StandardError
        nil
      end
    end
  else
    db
  end
end

Instance Method Details

#batch(await_durable: nil) {|batch| ... } ⇒ void

This method returns an undefined value.

Create and write a batch using a block.

Examples:

db.batch do |b|
  b.put("key1", "value1")
  b.put("key2", "value2")
  b.delete("old_key")
end

Parameters:

  • await_durable (Boolean) (defaults to: nil) —

    Whether to wait for durability (default: true)

Yields:

  • (batch) —

    Yields a WriteBatch to the block



211
212
213
214
215
 
# File 'lib/slatedb/database.rb', line 211

def batch(await_durable: nil)
  b = WriteBatch.new
  yield b
  write(b, await_durable: await_durable)
end

#begin_transaction(isolation: nil) {|txn| ... } ⇒ Transaction, Object

Begin a new transaction.

Examples:

Manual transaction management

txn = db.begin_transaction
txn.put("key", "value")
txn.commit

Block-based transaction (auto-commit)

db.transaction do |txn|
  txn.put("key", "value")
  txn.get("other_key")
end # automatically committed

Serializable isolation

db.transaction(isolation: :serializable) do |txn|
  val = txn.get("counter")
  txn.put("counter", (val.to_i + 1).to_s)
end

Parameters:

  • isolation (Symbol, String) (defaults to: nil) —

    Isolation level (:snapshot or :serializable)

Yields:

  • (txn) —

    If a block is given, yields the transaction and auto-commits/rollbacks

Returns:

  • (Transaction, Object) —

    The transaction (or block result if block given)



240
241
242
243
 
# File 'lib/slatedb/database.rb', line 240

def begin_transaction(isolation: nil)
  isolation_str = isolation&.to_s
  _begin_transaction(isolation_str)
end

#delete(key, await_durable: nil) ⇒ void

This method returns an undefined value.

Delete a key.

Examples:

Basic delete

db.delete("mykey")

Delete without waiting for durability

db.delete("mykey", await_durable: false)

Parameters:

  • key (String) —

    The key to delete

  • await_durable (Boolean) (defaults to: nil) —

    Whether to wait for durability (default: true)



115
116
117
118
119
120
121
 
# File 'lib/slatedb/database.rb', line 115

def delete(key, await_durable: nil)
  if await_durable.nil?
    _delete(key)
  else
    _delete_with_options(key, { await_durable: await_durable })
  end
end

#get(key, durability_filter: nil, dirty: nil, cache_blocks: nil) ⇒ String?

Get a value by key.

Examples:

Basic get

value = db.get("mykey")

Get with options

value = db.get("mykey", durability_filter: "memory", dirty: true)

Parameters:

  • key (String) —

    The key to look up

  • durability_filter (String, nil) (defaults to: nil) —

    Filter by durability level (“remote” or “memory”)

  • dirty (Boolean, nil) (defaults to: nil) —

    Whether to include uncommitted data

  • cache_blocks (Boolean, nil) (defaults to: nil) —

    Whether to cache blocks

Returns:

  • (String, nil) —

    The value, or nil if not found



61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/slatedb/database.rb', line 61

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

#put(key, value, ttl: nil, await_durable: nil) ⇒ void

This method returns an undefined value.

Store a key-value pair.

Examples:

Basic put

db.put("mykey", "myvalue")

Put with TTL

db.put("mykey", "myvalue", ttl: 60_000) # expires in 60 seconds

Put without waiting for durability

db.put("mykey", "myvalue", await_durable: false)

Parameters:

  • key (String) —

    The key to store

  • value (String) —

    The value to store

  • ttl (Integer, nil) (defaults to: nil) —

    Time-to-live in milliseconds

  • await_durable (Boolean) (defaults to: nil) —

    Whether to wait for durability (default: true)



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/slatedb/database.rb', line 91

def put(key, value, ttl: nil, await_durable: nil)
  opts = {}
  opts[:ttl] = ttl if ttl
  opts[:await_durable] = await_durable unless await_durable.nil?

  if opts.empty?
    _put(key, value)
  else
    _put_with_options(key, value, opts)
  end
end

#scan(start_key, end_key = nil, durability_filter: nil, dirty: nil, read_ahead_bytes: nil, cache_blocks: nil, max_fetch_tasks: nil) ⇒ Iterator

Scan a range of keys.

Examples:

Basic scan

iter = db.scan("a")
while entry = iter.next_entry
  key, value = entry
  puts "#{key}: #{value}"
end

Scan with range

iter = db.scan("a", "z")

Scan with block

db.scan("user:") do |key, value|
  puts "#{key}: #{value}"
end

Parameters:

  • start_key (String) —

    The start key (inclusive)

  • end_key (String, nil) (defaults to: nil) —

    The end key (exclusive). If nil, scans to end.

  • durability_filter (String, nil) (defaults to: nil) —

    Filter by durability level (“remote” or “memory”)

  • dirty (Boolean, nil) (defaults to: nil) —

    Whether to include uncommitted data

  • read_ahead_bytes (Integer, nil) (defaults to: nil) —

    Number of bytes to read ahead

  • cache_blocks (Boolean, nil) (defaults to: nil) —

    Whether to cache blocks

  • max_fetch_tasks (Integer, nil) (defaults to: nil) —

    Maximum number of fetch tasks

Returns:

  • (Iterator) —

    An iterator over key-value pairs



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/slatedb/database.rb', line 149

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

#snapshot {|snapshot| ... } ⇒ Snapshot, Object

Create a snapshot for consistent reads.

Examples:

Manual snapshot management

snapshot = db.snapshot
snapshot.get("key")
snapshot.close

Block-based snapshot (auto-close)

db.snapshot do |snap|
  snap.get("key1")
  snap.get("key2")
end # automatically closed

Yields:

  • (snapshot) —

    If a block is given, yields the snapshot and auto-closes

Returns:

  • (Snapshot, Object) —

    The snapshot (or block result if block given)



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/slatedb/database.rb', line 294

def snapshot
  snap = _snapshot

  if block_given?
    begin
      yield snap
    ensure
      begin
        snap.close
      rescue StandardError
        nil
      end
    end
  else
    snap
  end
end

#transaction(isolation: nil) {|txn| ... } ⇒ Object

Execute a block within a transaction.

The transaction is automatically committed if the block succeeds, or rolled back if an exception is raised.

Examples:

result = db.transaction do |txn|
  old_val = txn.get("counter") || "0"
  new_val = (old_val.to_i + 1).to_s
  txn.put("counter", new_val)
  new_val
end

Parameters:

  • isolation (Symbol, String) (defaults to: nil) —

    Isolation level (:snapshot or :serializable)

Yields:

  • (txn) —

    Yields the transaction to the block

Returns:

  • (Object) —

    The result of the block



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/slatedb/database.rb', line 262

def transaction(isolation: nil)
  txn = begin_transaction(isolation: isolation)
  begin
    result = yield txn
    txn.commit
    result
  rescue StandardError
    begin
      txn.rollback
    rescue StandardError
      nil
    end
    raise
  end
end

#write(batch, await_durable: nil) ⇒ void

This method returns an undefined value.

Write a batch of operations atomically.

Examples:

Write a batch

batch = SlateDb::WriteBatch.new
batch.put("key1", "value1")
batch.put("key2", "value2")
batch.delete("key3")
db.write(batch)

Using batch block helper

db.batch do |b|
  b.put("key1", "value1")
  b.put("key2", "value2")
end

Parameters:

  • batch (WriteBatch) —

    The batch to write

  • await_durable (Boolean) (defaults to: nil) —

    Whether to wait for durability (default: true)



190
191
192
193
194
195
196
 
# File 'lib/slatedb/database.rb', line 190

def write(batch, await_durable: nil)
  if await_durable.nil?
    _write(batch)
  else
    _write_with_options(batch, { await_durable: await_durable })
  end
end