lkv

A lightweight and fast embedded key-value store for Rust.

Overview

lkv is a lightweight and fast embedded database implemented in Rust. It is designed specifically for read performance based on hash tables and memory efficiency, featuring faster lookups than LMDB, sled, redb, and others.

To maintain structural simplicity and read performance, lkv comes with a very limited set of features. Here is what lkv supports:

• Writing and reading arbitrary byte sequences [u8] as Key/Value
• Fast, unordered scans
• Fast and zero-copy lookups
• Transactions
• Snapshots
• Explicit compaction

On the other hand, the following features are not supported:

• Reading and writing from multiple processes
• Multiple writers
• Advanced queries such as ranged or prefix queries
• Automatic compaction

Due to its performance characteristics, it is suitable for lightweight configuration persistence or managing master data that rarely changes. Conversely, using it as a general-purpose database with frequent updates is not recommended.

Much of lkv's design is inspired by LinkedIn's PalDB and Bitcask. In addition, some ideas are based on FASTER.

For details, refer to docs/design.md.

Installation

cargo add lkv

Quick Start

use lkv::{Database, Result};

fn main() -> Result<()> {
    let mut db = Database::create("./example.lkv")?;

    let mut write = db.begin_write()?;
    write.put("name", "lkv")?;
    write.commit()?;

    let read = db.begin_read()?;
    assert_eq!(read.get("name")?, Some(b"lkv".as_slice()));
    for item in read.iter()? {
        let (key, value) = item?;
        println!("{} = {}",
            String::from_utf8_lossy(key),
            String::from_utf8_lossy(value));
    }
    drop(read);

    Ok(())
}

Snapshots

When writing to the database using WriteTransaction in lkv, you cannot perform reads at the same time. If you want to read from the database during a write, you can create a snapshot with snapshot() and read through it.

let snapshot = db.snapshot()?;
let old_value = snapshot.get("key")?;
for item in snapshot.iter()? {
    let (key, value) = item?;
}

In-Memory

It is also possible to use lkv as an in-memory database.

let mut db = Database::memory();

The API is identical to that of a regular database, but it operates in memory without creating a file.

Benchmark

The benchmarks were conducted using a MacBook Pro with an Apple M2 chip and 24 GB of RAM.

License

MIT