Crate lsm_db 

lsm-db

A log-structured merge-tree storage engine for Rust.

An LSM engine is the write path that powers RocksDB, LevelDB, Cassandra, and ScyllaDB: writes accumulate in a sorted in-memory buffer (the memtable); when the buffer fills it is flushed to an immutable, sorted file on disk (an SSTable); reads consult the buffer first and fall through to the file. The design turns random writes into sequential disk writes, which is why it underpins so many write-heavy stores.

lsm-db packages that write path as a small, audited library so the storage engines in the portfolio — txn-db, Hive DB — share one implementation rather than each re-deriving it.

The Tier-1 API

The common case is five calls: open, put, get, delete, scan.

use lsm_db::Lsm;

// Open (or create) a database backed by a directory.
let dir = tempfile::tempdir()?;
let db = Lsm::open(dir.path())?;

// Write and read arbitrary byte keys and values.
db.put(b"user:1", b"alice")?;
db.put(b"user:2", b"bob")?;
assert_eq!(db.get(b"user:1")?, Some(b"alice".to_vec()));

// Delete masks the key.
db.delete(b"user:1")?;
assert_eq!(db.get(b"user:1")?, None);

// Range scans walk keys in sorted order.
db.put(b"user:1", b"alice")?;
let users: Vec<_> = db.scan(b"user:".to_vec()..b"user;".to_vec())?.collect();
assert_eq!(users.len(), 2);

Tuning

LsmConfig is the Tier-2 surface for tuning the write-buffer size. Pass it to Lsm::open_with; Lsm::open uses the defaults.

use lsm_db::{Lsm, LsmConfig};
let dir = tempfile::tempdir()?;
let db = Lsm::open_with(dir.path(), LsmConfig::new().memtable_capacity(1 << 20))?;
db.put(b"k", b"v")?;

Grouped writes

Batch applies several writes as one atomic group; see Lsm::write.

Durability

Flushed runs are fsynced and recorded in a manifest, so flushed data survives reopening, and the on-disk format is frozen for the 1.x series. Writes still buffered in the memtable when a process exits without flushing are durable only with the durability feature: it logs every write to a wal-db write-ahead log before acknowledging it and replays the log on open, so no acknowledged write is lost across a crash.

Feature flags

Feature	Default	Description
std	yes	Standard library. The engine requires it.
durability	no	Crash-safe writes via a wal-db write-ahead log.
bloom	no	Bloom-filtered point lookups via bloom-lib.

Modules

preludestd

The crate’s common imports in one use.

Structs

Batchstd

An ordered group of writes applied together.

Lsmstd

A log-structured merge-tree key-value store backed by a directory on disk.

LsmConfigstd

Tuning parameters for an Lsm engine.

Scanstd

An ascending iterator over a key range, returned by Lsm::scan.

Enums

Errorstd

Everything that can go wrong while opening, reading from, writing to, or flushing an Lsm engine.

Constants

DEFAULT_BLOCK_CACHE_CAPACITYstd

Default block-cache capacity: 8 MiB of decoded data blocks.

DEFAULT_COMPACTION_TRIGGERstd

Default number of on-disk runs that triggers a background compaction.

DEFAULT_MEMTABLE_CAPACITYstd

Default memtable capacity: 4 MiB of live key and value bytes.

Type Aliases

Resultstd

A specialised Result for storage-engine operations.