regolith 0.1.0

Pre-1.0. The public surface is small and stable-shaped, but breakage is allowed until 1.0.

Install

[dependencies]
regolith = "0.1"

Quick start

use regolith::{Db, Options, WriteBatch};

let db = Db::open("/tmp/my_db", Options::default())?;

db.put(b"hello", b"world")?;
assert_eq!(db.get(b"hello")?.as_deref(), Some(&b"world"[..]));
db.delete(b"hello")?;

// A batch applies atomically: all of it, or none of it.
let mut batch = WriteBatch::new();
batch.put(b"a", b"1");
batch.put(b"b", b"2");
db.write(batch)?;

// A snapshot is a point in time. Later writes are invisible to it.
let snap = db.snapshot();
db.put(b"a", b"changed")?;
assert_eq!(snap.get(b"a")?.as_deref(), Some(&b"1"[..]));

for (key, value) in db.scan(Some(b"a"), Some(b"z"))? {
    println!("{key:?} = {value:?}");
}

Reads that should not copy use get_slice, which borrows the bytes the database already holds:

if let Some(slice) = db.get_slice(b"a")? {
    assert_eq!(&*slice, b"1");
}

Transactions

Pick the isolation a unit of work actually needs. The level decides how much of the transaction's footprint is validated at commit, so a stricter level refuses more and commits fewer.

use regolith::{IsolationLevel, OptimisticTransactionDb, Options};

let db = OptimisticTransactionDb::open("/tmp/txn_db", Options::default())?;

let mut txn = db.begin_transaction_with(IsolationLevel::Serializable);
let balance = txn.get(b"account")?.unwrap_or_default();
txn.put(b"account", b"debited")?;
txn.commit()?;

TransactionDb is the pessimistic flavour: it takes key locks, so contention waits instead of retrying. OptimisticTransactionDb validates at commit and retries.

Commits report the sequence they landed at, so an upper layer can order its own versions against the store without a lock of its own:

let seq = db.write_sequenced(batch)?;
assert!(db.snapshot().sequence() >= seq);

Durability

DurabilityMode::Eventual (default) hands every write to the kernel but does not fsync: a committed write survives a process crash, not a power loss. DurabilityMode::Immediate fsyncs, and every write that returned Ok survives a power cut.

Either way, recovery reaches a valid prefix of the write history: some number of writes applied, in order, no gaps, no half-applied batch. A WriteBatch is atomic under both modes.

Platforms

Pure Rust throughout: no C toolchain, no FFI, no linker surprises. Compaction runs on an ordinary OS thread; no async runtime is required. On a target without threads, set max_background_compactions = 0 and compaction runs on the calling thread.

Configuration

use regolith::{CompressionType, Options};

let opts = Options {
    write_buffer_size: 64 * 1024 * 1024,
    block_cache_size: 512 * 1024 * 1024,
    compression: CompressionType::Lz4,
    ..Default::default()
};

Three ready-made profiles: Options::default() for a server, Options::embedded() for a 1-4 MiB budget, and Options::wasm() for a browser or wasi module. Every value and the reasoning behind it is documented on the profile itself.

Two knobs deserve a warning:

• Value size. max_value_size defaults to 64 MiB. Values are stored inline, with no key-value separation, so a large value is rewritten in full by every compaction that touches its key. A 1 GiB value peaked at 3719 MiB RSS.
• Back-pressure under FIFO and universal compaction. level0_stop_writes_trigger counts L0 files, and only CompactionStyle::Level reduces that count. Under the other styles the trigger can be reached and never relieved, and writes then fail with Error::Busy naming the knob. Set both L0 triggers to 0 there and bound memory with max_write_buffer_number and hard_pending_compaction_bytes_limit.

How it works

         writes ──> WAL ──> MemTable ──> reads
                             │ flush
                        ┌────▼─────┐
                        │  L0 SSTs │  may overlap
                        └────┬─────┘
                             │ compaction
                        ┌────▼─────┐
                        │ L1..L6   │  sorted, non-overlapping, 10x each
                        └──────────┘

Write: append to the WAL, insert into an arena-backed skip-list memtable, and when it fills, flush to an L0 SSTable. Background compaction merges levels.

Read: active memtable, then frozen memtables, then L0 (bloom pre-check), then L1+ by binary search. First hit wins.

MVCC: every write takes a sequence number. A snapshot captures the current one and ignores anything newer, so reads need no locks.

Testing

The suite is the argument for trusting any of the above.

just gate       # format, lint, docs, tests, dependency audit
just test       # the whole suite under cargo-nextest
just loom-all   # exhaustive model checking of the publication protocols
just elle       # Elle consistency checking of transaction histories
just chaos      # the full-size read-view chaos workload
just wasm       # the wasm32-wasip1 lifecycle under wasmtime

Each badge above is a workflow of its own, so a red one names exactly which property regressed.

License

Dual-licensed under Apache-2.0 or MIT, at your option.