heed

heed is a Rust wrapper around LMDB (Lightning Memory-Mapped Database) that lets applications store and retrieve strongly-typed Rust values in a memory-mapped, ACID-transactional key-value store, without giving up the raw performance LMDB is known for. Types are enforced at compile time through generic Database<KeyCodec, ValueCodec> handles, so a database opened for one key/value type can’t accidentally be read or written as another.

Built and maintained by the team behind Meilisearch, heed is the storage layer several production search and indexing systems are built on, and ships with heed-types codecs for common encodings (bincode, serde_json, rmp_serde) plus a heed3 variant tracking LMDB’s newer mdb.master3 branch with encryption-at-rest and checksumming.

What You Get

• Compile-time typed Database<KeyCodec, ValueCodec> handles over raw LMDB key/value pairs
• Safe wrappers for LMDB environments, read/write transactions, and cursors
• Built-in codecs (heed-types) for common formats: bincode, serde_json, rmp_serde, byteorder-based numerics
• A cookbook module with complete, runnable example programs
• Feature flags for POSIX semaphores, extended key-length limits, and Valgrind support
• A heed3 variant tracking LMDB’s newer branch with encryption-at-rest and checksumming

Common Use Cases

• Building an embedded, memory-mapped key-value store for a search or indexing engine
• Persisting strongly-typed application state without a separate database server
• Storing serialized documents (via serde/bincode) with ACID transaction guarantees
• Replacing a hand-rolled unsafe LMDB FFI layer with a type-checked, ergonomic API

Under The Hood

Architecture: The workspace separates concerns cleanly: lmdb-master-sys/lmdb-master3-sys (heed/../lmdb-master-sys) compile and bind the vendored LMDB C library via build.rs, heed-traits defines the BytesEncode/BytesDecode traits that make the codec system pluggable, heed-types implements concrete codecs against those traits, and the top-level heed crate (heed/src/lib.rs, envs, txn.rs, cursor.rs, databases) composes all of this into Env, RwTxn/RoTxn, and Database<KC, DC> types that encode/decode through the trait bounds at compile time.

Tech Stack: Rust 2021 edition, wrapping the C LMDB library directly (no external database process). Core dependencies are narrowly scoped: libc for FFI primitives, byteorder for numeric codecs, bitflags for LMDB flag types, once_cell and synchronoise for internal synchronization. Serialization support (serde, serde_json, bincode, rmp_serde) is entirely feature-gated so consumers only pull in what they use.

Code Quality: #![warn(missing_docs)] is set at the crate root, and the module is extensively doc-commented with runnable doctest examples embedded directly in lib.rs. A dedicated examples/ directory (all-types, cursor-append, custom-comparator, nested-rtxns, multi-env, etc.) exercises real usage patterns beyond unit tests, and dev-dependencies include rand, rayon, and roaring for exercising concurrent and bulk-data scenarios.

API Design: The generic Database<KC, DC> handle pattern makes the type contract explicit at the call site — env.create_database::<Str, U32<NativeEndian>>() reads as self-documenting compared to raw byte-slice LMDB bindings. The trade-off is that newcomers must learn heed’s codec-trait vocabulary (BytesEncode/BytesDecode, the heed::types::* codec set) before the type parameters make sense, though the bundled cookbook examples substantially shorten that ramp-up.