driftdb/lib.rs
1//! # driftdb
2//!
3//! Embeddable LSM-tree key-value engine. Write path:
4//! `put → WAL (group-commit fsync) → memtable → freeze → flush → L0 SST → compactor → L1+`.
5//! Read path: memtable → frozen memtable(s) → L0 (newest first) → L1+ (binary search,
6//! bloom-filtered inside each SST). Keys carry a `(user_key, seqno)` pair for MVCC snapshot
7//! reads; a single dedicated writer thread group-commits batches to the WAL, and a single
8//! background thread owns flush + leveled compaction.
9//!
10//! Internals (threads, locks, recovery, invariants) are documented in
11//! [ARCHITECTURE.md](https://github.com/Bunty9/driftdb/blob/main/docs/ARCHITECTURE.md);
12//! on-disk formats in the [README](https://github.com/Bunty9/driftdb#on-disk-formats).
13//!
14//! ## Installation
15//!
16//! The crate is published as `driftdb-lsm` (the `driftdb` name on crates.io belongs to an
17//! unrelated project), but the library is imported as `driftdb`:
18//!
19//! ```toml
20//! [dependencies]
21//! driftdb-lsm = "0.1"
22//! ```
23//!
24//! Linux only for now: the WAL uses `fdatasync(2)` and the directory lock uses `flock(2)`.
25//!
26//! ## Quick start
27//!
28//! ```no_run
29//! use driftdb::{Db, Result};
30//!
31//! # async fn run() -> Result<()> {
32//! let db = Db::open("/tmp/driftdb-demo").await?;
33//! db.put(b"hello", b"world").await?;
34//! assert_eq!(db.get(b"hello").await?.as_deref(), Some(&b"world"[..]));
35//! db.flush().await?; // force a flush to L0, just to demonstrate it's there
36//! assert_eq!(db.get(b"hello").await?.as_deref(), Some(&b"world"[..]));
37//! # Ok(())
38//! # }
39//! ```
40
41#![deny(rust_2018_idioms)]
42#![warn(missing_debug_implementations)]
43#![warn(missing_docs)]
44
45// The WAL relies on `fdatasync(2)` and the directory lock on `flock(2)`. macOS has no
46// `fdatasync` (it would need `fcntl(F_FULLFSYNC)`) and Windows has neither, so fail with a
47// readable message instead of an unresolved-import error from deep inside `libc`.
48#[cfg(not(target_os = "linux"))]
49compile_error!("driftdb currently supports Linux only (it needs fdatasync(2) and flock(2)).");
50
51// Internal modules. Not `pub`: the public surface is the re-exports below plus `__bench`. A
52// private `mod` declared at the crate root is still reachable from every other module in the
53// crate (privacy is scoped to the declaring module and its descendants, and every module is a
54// descendant of the root) -- it just isn't reachable from outside the crate, which is the point.
55mod compaction;
56mod db;
57mod error;
58mod iter;
59mod manifest;
60mod memtable;
61mod sstable;
62mod wal;
63
64pub use crate::db::{Db, Options, Snapshot, Stats, WriteBatch};
65pub use crate::error::{Error, Result};
66pub use crate::wal::{MAX_KEY_LEN, MAX_VALUE_LEN};
67
68/// On-disk format version shared by the manifest log and the SSTable footer. Bump this whenever
69/// the WAL, SST, or manifest byte layout changes in a way an older or newer build can't read;
70/// [`Db::open`] refuses a directory written by an unsupported version (see
71/// [`Error::UnsupportedFormat`]) instead of misreading it.
72pub(crate) const FORMAT_VERSION: u32 = 1;
73
74/// Not part of the public API; no semver guarantees; for benches only.
75///
76/// `benches/report.rs`'s raw WAL-replay bench needs to drive `WalFile`/`replay` directly
77/// (bypassing `Db` entirely) to isolate the replay decode path from the cost of flushing to an
78/// SST on recovery. Everything else should go through [`Db`].
79#[doc(hidden)]
80pub mod __bench {
81 pub use crate::memtable::Value;
82 pub use crate::wal::{replay, wal_path, WalFile};
83}