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 (
Arcunder the hood). Every write blocks on the writer thread’s group commit; every read is lock-free past a couple of shortRwLockreads. - 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.
- Write
Batch - 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 withcrate::Error::InvalidArgument.Dbrejects oversized inputs before they ever reach here — this module onlydebug_asserts it. - MAX_
VALUE_ LEN - Maximum value length accepted by
crate::Db::put/crate::Db::write_batch(256 MiB); longer values fail withcrate::Error::InvalidArgument.Dbrejects oversized inputs before they ever reach here — this module onlydebug_asserts it.
Type Aliases§
- Result
- Crate-wide
Resultalias.