Close the database and release the file handle and path lock. Does not fsync — if using ManualSync, call file_sync before closing to ensure durability. The Db handle must not be used after calling this.

Panics if the store file handle cannot be closed.

trove.close(db)

Trigger a manual compaction. Rebuilds the store file keeping only live entries, resetting the dirt factor to zero. Returns Ok(Nil) on success or Error(reason) if compaction failed. On failure the database remains functional with the original store file.

The timeout is separate from call_timeout because compaction can take much longer than normal operations.

let assert Ok(Nil) = trove.compact(db, timeout: 60_000)

Remove a key. No error if the key does not exist.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.delete(db, key: "hello")

Atomically delete multiple keys.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.delete_multi(db, keys: ["a", "b"])

Returns the current dirt factor: a float between 0.0 and 1.0 that approximates how much of the store file is occupied by superseded data. Overwrites and deletes increment the dirt counter because they write new nodes that make old ones unreachable. New inserts do not increment dirt since they don’t supersede existing data. The formula is dirt / (1 + size + dirt) — the +1 ensures the result is always well-defined, even for an empty tree. The value approaches but never reaches 1.0. Higher values mean more wasted space that compaction would reclaim.

let df = trove.dirt_factor(db)

Force an fsync of the store file to disk. Useful when auto_file_sync is set to ManualSync and you want to control when data is flushed.

Panics if the fsync system call fails.

let config = trove.Config(..config, auto_file_sync: trove.ManualSync)
let assert Ok(db) = trove.open(config)
trove.put(db, key: "hello", value: "world")
trove.file_sync(db)

Look up a key. Returns Ok(value) if found, Error(Nil) if the key does not exist.

Panics on store I/O or decode errors (e.g. file corruption).

let assert Ok("world") = trove.get(db, key: "hello")

Check whether a key exists in the database.

Panics on store I/O or decode errors (e.g. file corruption).

let assert True = trove.has_key(db, key: "hello")

Returns True if the database contains no entries.

let empty = trove.is_empty(db)

Open a database at the configured path. Creates the directory if it does not exist. If a store file already exists, recovers the tree from the latest valid header.

let config = trove.Config(
  path: "./my_db",
  key_codec: codec.string(),
  value_codec: codec.string(),
  key_compare: string.compare,
  auto_compact: trove.NoAutoCompact,
  auto_file_sync: trove.AutoSync,
  call_timeout: 5000,
)
let assert Ok(db) = trove.open(config)

Insert or update a key-value pair.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.put(db, key: "hello", value: "world")

Atomically insert and delete entries in a single operation. Puts are applied first, then deletes, all under a single header write.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.put_and_delete_multi(
  db,
  puts: [#("new_key", "value")],
  deletes: ["old_key"],
)

Atomically insert multiple key-value pairs. A single header write covers the entire batch.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.put_multi(db, entries: [#("a", "1"), #("b", "2")])

Iterate over entries in the database within optional key bounds. Returns a List of key-value pairs.

For large result sets, use with_snapshot and snapshot_range instead to stream entries lazily without loading them all at once.

Panics if the snapshot file handle cannot be opened, or on store read/decode errors during iteration.

Use range.Inclusive(key) or range.Exclusive(key) for bounds, or option.None for unbounded. Use range.Forward or range.Reverse for direction.

import gleam/option.{Some}
import trove/range

let results =
  trove.range(
    db,
    min: Some(range.Inclusive("a")),
    max: Some(range.Exclusive("z")),
    direction: range.Forward,
  )

Change the auto-compaction setting at runtime.

trove.set_auto_compact(db, trove.AutoCompact(min_dirt: 100, min_dirt_factor: 0.25))

Returns the number of live entries in the database.

let count = trove.size(db)

Look up a key in a snapshot. Returns Error(Nil) if the key does not exist.

Panics on store read or decode errors (e.g. file corruption).

trove.with_snapshot(db, fn(snap) {
  let assert Ok(value) = trove.snapshot_get(snapshot: snap, key: "my_key")
  value
})

Iterate over entries in a snapshot within optional key bounds. Returns a lazy Yielder that streams entries from disk on demand, reading only one leaf node at a time.

The yielder holds a reference to the snapshot’s file handle, so it must be consumed before the snapshot is closed. For large ranges, prefer this over range to avoid loading all entries into memory.

Panics on store read or decode errors during iteration (e.g. file corruption).

Use range.Inclusive(key) or range.Exclusive(key) for bounds, or option.None for unbounded. Use range.Forward or range.Reverse for direction.

import gleam/option.{None, Some}
import gleam/yielder
import trove/range

let entries = trove.with_snapshot(db, fn(snap) {
  let y = trove.snapshot_range(
    snapshot: snap,
    min: Some(range.Inclusive("a")),
    max: None,
    direction: range.Forward,
  )
  yielder.to_list(y)
})

Run an atomic transaction. The callback receives a Tx handle and must return Commit(tx:, result: value) to apply writes or Cancel(result: value) to discard. The transaction holds exclusive write access for its duration.

The timeout parameter (in milliseconds) controls how long the caller waits for the transaction to complete, including queue wait time and callback execution. Choose a value appropriate for your workload — queued operations or auto-compaction may delay the start, and a long-running callback consumes the remaining budget.

Important: The callback runs inside the database actor. Do not call any trove functions (such as get, put, compact, etc.) on the same Db handle from within the callback — this will deadlock the actor until the call timeout fires. Use the Tx handle (tx_get, tx_put, tx_delete) for all reads and writes inside the transaction.

Panics if the Commit variant contains a stale or replaced Tx handle (e.g. the original handle instead of the latest one returned by tx_put/tx_delete).

Non-escaping: The Tx handle is only valid inside the callback. Do not store it in a variable, send it to another process, or return it — using a Tx after the callback returns will panic or produce undefined behavior.

Timeout semantics: If the timeout fires while the callback is still executing, the caller panics but the actor continues running the callback to completion. This means writes may be durably committed even though the caller observes a timeout failure. Choose a timeout that accommodates your expected callback duration and any queued operations ahead of it.

let result = trove.transaction(db, timeout: 5000, callback: fn(tx) {
  let tx = trove.tx_put(tx, key: "key", value: "value")
  trove.Commit(tx:, result: "done")
})

Delete a key within a transaction. Returns the updated Tx.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.transaction(db, timeout: 5000, callback: fn(tx) {
  let tx = trove.tx_delete(tx, key: "old_key")
  trove.Commit(tx:, result: Nil)
})

Read a key within a transaction. Sees writes made earlier in the same transaction. Returns Error(Nil) if the key does not exist.

Panics on store I/O or decode errors (e.g. file corruption).

trove.transaction(db, timeout: 5000, callback: fn(tx) {
  let assert Ok(current) = trove.tx_get(tx, key: "counter")
  let tx = trove.tx_put(tx, key: "counter", value: current <> "!")
  trove.Commit(tx:, result: Nil)
})

Check whether a key exists within a transaction. Sees writes made earlier in the same transaction.

Panics on store I/O or decode errors (e.g. file corruption).

trove.transaction(db, timeout: 5000, callback: fn(tx) {
  let exists = trove.tx_has_key(tx, key: "counter")
  trove.Commit(tx:, result: exists)
})

Write a key-value pair within a transaction. Returns the updated Tx.

Panics on store I/O errors (e.g. disk full, file corruption).

trove.transaction(db, timeout: 5000, callback: fn(tx) {
  let tx = trove.tx_put(tx, key: "greeting", value: "hello")
  trove.Commit(tx:, result: Nil)
})

Run a callback with a point-in-time snapshot. The snapshot sees the state of the database at the moment it was acquired — subsequent writes are invisible to it.

Non-escaping: The Snapshot handle is only valid inside the callback. Do not store it in a variable, send it to another process, or return it — using a Snapshot after the callback returns will panic or produce undefined behavior because the underlying file handle is closed on exit.

Panics if the snapshot file handle cannot be opened.

let result = trove.with_snapshot(db, fn(snap) {
  trove.snapshot_get(snapshot: snap, key: "my_key")
})
// result: Result(String, Nil)