TurboKV is an async embedded key-value database with atomic batches, ordered range scans, configurable durability, compression, and background compaction.

Installation

cargo add turbokv
cargo add tokio --features full

Or add the dependencies directly:

[dependencies]
turbokv = "0.6"
tokio = { version = "1", features = ["full"] }

TurboKV's persisted Bloom-filter format uses hardware AES. Build x86/x86_64 targets with RUSTFLAGS="-C target-feature=+aes,+sse2", and ARM/AArch64 targets with RUSTFLAGS="-C target-feature=+aes,+neon". You may instead use -C target-cpu=native when the binary will run only on the same CPU model or a feature superset.

Quick start

use turbokv::{Db, DbOptions, WriteBatch};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Db::open_with_options("./my-database", DbOptions::durable()).await?;

    db.insert(b"user:1", b"Ada").await?;
    assert_eq!(db.get(b"user:1").await?, Some(b"Ada".to_vec()));

    let mut batch = WriteBatch::new();
    batch.put(b"user:2", b"Grace");
    batch.put(b"user:3", b"Linus");
    batch.delete(b"user:1");
    db.write_batch(&batch).await?;

    for (key, value) in db.scan_prefix(b"user:").await? {
        println!(
            "{} = {}",
            String::from_utf8_lossy(&key),
            String::from_utf8_lossy(&value)
        );
    }

    db.close().await?;
    Ok(())
}

Runnable examples:

• basic: insert, get, update, and remove
• batch_writes: atomic puts and deletes
• range_queries: ordered range and prefix scans
• concurrent: shared access from Tokio tasks
• persistence: paranoid WAL recovery
• configuration: cache, memtable, and compression options

API breakdown

Durability presets

Durable does not leave the WAL unsynchronized forever. A successful explicit or background memtable flush and a clean close synchronize it; rotating a full WAL segment also synchronizes the finalized segment. With the defaults, the memtable rotates at approximately 64 MiB, the background task checks for immutable memtables every 60 seconds, and a WAL segment rotates at 1 GiB. These checkpoints let older writes survive a power loss when the filesystem and device honor the sync, but they do not impose an exact 64 MiB loss bound: flush is asynchronous, memory accounting is approximate, and a large mutation can cross a threshold. Use Paranoid when every successful acknowledgement must cross a storage sync barrier.

One open Db or Engine exclusively owns its data directory. Use close() or close_with_status() for a clean shutdown; dropping a handle is not a clean shutdown contract.

Database operations

Keys and values are arbitrary byte sequences supplied through AsRef<[u8]>; strings need to be encoded by the caller. Mutation APIs copy their inputs before returning. Point and collecting reads return owned Vec<u8> values. An empty value is valid data and is distinct from a deleted key.

Opening and configuration

All presets start with a 64 MiB memtable, a 64 MiB block cache, and LZ4 compression. Their public fields can be adjusted before opening:

Point, bulk, and batch operations

With the WAL enabled, one record or complete batch must fit in the WAL's u32 payload length. A failed or cancelled mutation may already have reached the WAL; inspect the key or reopen before retrying a non-idempotent operation.

WriteBatch owns copies of every key and value:

Range and prefix scans

Keys are ordered lexicographically by raw bytes. Every scan captures a coherent point-in-time view. Creating one can freeze a nonempty active memtable, so frequent small scans may increase later flush work.

Advancing a streaming iterator is synchronous and may perform mmap reads, checksum validation, decompression, and cache locking. Drop it promptly: the iterator pins its snapshot readers and database-directory ownership.

Persistence, maintenance, and statistics

Most database methods return DbError. Streaming iterator creation returns DbError, while failures discovered later are yielded as ScanError. The lower-level Engine and component configuration types are supported advanced APIs; their complete field and method contracts are in the crate documentation.

Benchmarks

The benchmark used TurboKV 0.6.0, fjall 2.11.2, and redb 2.6.3 over three repetitions. Throughput is acknowledged keys per second; higher is better.

Fast disables the WAL. Durable writes a recoverable WAL record without syncing each acknowledgement to persistent storage. Paranoid performs that sync before returning; its single-key throughput is therefore bounded by storage-sync latency, while explicit batches amortize one barrier across many keys.

Protocol: 200,000 deterministic 20-byte keys, 400-byte values (84 MB logical input, above the 64 MiB memtable), one caller, atomic batches where shown, compression and block cache disabled, and an uncleared OS page cache. redb 2.6.3's Durability::Eventual performs a macOS F_BARRIERFSYNC for every transaction, while the TurboKV Recoverable and fjall Buffer modes stop at their process-crash-recoverable OS-cache boundaries. Batching amortizes that fixed redb barrier; its single-key rows are therefore architectural context rather than a like-for-like durability claim. Cross-engine settled timings are not compared.

Measured across 2026-08-28–29 with an Apple M4 (Mac16,1), 32 GiB RAM, macOS 15.3.2 (24D81), APFS, and rustc 1.88.0. Exact raw repetitions, latency percentiles, dispersion, dependency versions, byte accounting, and amplification for the three TurboKV columns are in the mode JSON artifact and its text report. The fjall and redb columns come from the matching retained cross-engine artifact. The full methodology and rerun command are in benchmarks/README.md.