Skip to main content

Crate driftdb

Crate driftdb 

Source
Expand description

§driftdb

Embeddable LSM-tree key-value engine. Write path: put → WAL (group-commit fsync) → memtable → freeze → flush → L0 SST → compactor → L1+. Read path: memtable → frozen memtable(s) → L0 (newest first) → L1+ (binary search, bloom-filtered inside each SST). Keys carry a (user_key, seqno) pair for MVCC snapshot reads; a single dedicated writer thread group-commits batches to the WAL, and a single background thread owns flush + leveled compaction.

Internals (threads, locks, recovery, invariants) are documented in ARCHITECTURE.md; on-disk formats in the README.

§Installation

The crate is published as driftdb-lsm (the driftdb name on crates.io belongs to an unrelated project), but the library is imported as driftdb:

[dependencies]
driftdb-lsm = "0.1"

Linux only for now: the WAL uses fdatasync(2) and the directory lock uses flock(2).

§Quick start

use driftdb::{Db, Result};

let db = Db::open("/tmp/driftdb-demo").await?;
db.put(b"hello", b"world").await?;
assert_eq!(db.get(b"hello").await?.as_deref(), Some(&b"world"[..]));
db.flush().await?; // force a flush to L0, just to demonstrate it's there
assert_eq!(db.get(b"hello").await?.as_deref(), Some(&b"world"[..]));

Structs§

Db
The public handle. Cheap to clone (Arc under the hood). Every write blocks on the writer thread’s group commit; every read is lock-free past a couple of short RwLock reads.
Options
Engine tuning knobs. See each field for the default (matches the phase-2 plan).
Snapshot
A point-in-time read view. Registers its seqno in the snapshot table on creation and unregisters on drop; while at least one snapshot is registered at or below a given seqno, the compactor keeps every version a read at that seqno (or lower) might need.
Stats
Per-level file counts + byte totals, plus write-amplification inputs.
WriteBatch
A batch of puts/deletes applied atomically: one writer-thread request, consecutive seqnos, one ack.

Enums§

Error
Crate-wide error type. See module docs for the full taxonomy.

Constants§

MAX_KEY_LEN
Maximum key length accepted by crate::Db::put/crate::Db::delete/ crate::Db::write_batch; longer keys fail with crate::Error::InvalidArgument. Db rejects oversized inputs before they ever reach here — this module only debug_asserts it.
MAX_VALUE_LEN
Maximum value length accepted by crate::Db::put/crate::Db::write_batch (256 MiB); longer values fail with crate::Error::InvalidArgument. Db rejects oversized inputs before they ever reach here — this module only debug_asserts it.

Type Aliases§

Result
Crate-wide Result alias.