obkv

obkv is a micro key-value store for Rust in which the key is always exactly one byte, giving up to 256 possible entries per object. It serializes a set of small keyed byte payloads into a single compact buffer that can be written once and read back by key with zero-copy access.

Inspired by the KVDS crate, obkv is intentionally tiny — roughly 15 KB of Rust — and is used inside Meilisearch to pack field data efficiently. Its KvWriter/KvReader pair makes it easy to build an in-memory blob and later look up values without deserializing the whole thing.

What You Get

• KvWriter for building a one-byte-keyed object in memory or into any writer.
• KvReader for looking up values by their single-byte key without full deserialization.
• A compact on-buffer layout using variable-length integers for value lengths.
• Zero-copy reads that return borrowed slices into the underlying buffer.
• A tiny, dependency-light footprint suitable for embedding in performance-sensitive code.

Common Use Cases

• Packing a small, fixed set of fields (up to 256) into one compact blob.
• Storing per-document field data efficiently inside a search index.
• Serializing keyed byte payloads where keys naturally fit in a single byte.
• Reading specific values back by key without allocating or parsing the whole object.

Under The Hood

Architecture — obkv is two small modules: lib.rs implements the KvWriter and KvReader over a byte buffer, and varint.rs provides variable-length integer encoding used to store value lengths compactly. Writing appends each (u8 key, &[u8] value) pair with a varint-encoded length; reading scans or indexes into the buffer to return borrowed slices, so lookups produce zero-copy references rather than owned copies.

Tech Stack — Pure Rust (with a tiny shell helper) and essentially no runtime dependencies, keeping it lightweight and fast to compile. MIT-licensed and marked minimalist/lightweight in its crate keywords.

Code Quality — The crate is small enough to fully audit; lib.rs carries a documented usage example and an inline test, and the design is deliberately narrow, which limits the surface for bugs. It is battle-tested as a Meilisearch dependency despite low standalone repository activity.

API Design — The API is minimal and intuitive: create a writer, insert byte keys and values, finalize with into_inner, then wrap the bytes in a KvReader and get by key. There is almost no boilerplate and the single-byte-key constraint keeps the mental model simple; the main thing to learn is that it is a serialization format, not a general database.