natdb 0.1.1

Safe, idiomatic Rust bindings for LMDB 1.0 (maintained fork of lmdb-rkv).
Documentation

natdb

Safe, idiomatic Rust bindings for the Lightning Memory-Mapped Database (LMDB), built on LMDB 1.0.2.

The workspace has two crates:

Crate What it is
natdb Safe API: environments, databases, read-only / read-write / nested transactions, cursors and iterators, zero-copy reserve, statistics.
natdb-sys Raw FFI declarations for the full LMDB 1.0.2 API (lmdb.h), and the build script that compiles the vendored C sources.

LMDB is compiled from the official sources vendored in natdb-sys/lmdb/; no system library is used. The bindings are generated by bindgen and committed, so building does not need libclang.

Supported platforms: macOS, iOS (device and simulator), Android (arm64-v8a, armeabi-v7a, x86, x86_64), Linux and Windows. On Apple targets LMDB locks with process-shared pthread mutexes stored in the lock file: the App Sandbox of iOS and macOS forbids SysV semaphores and unprefixed named POSIX semaphores.

LMDB 1.0 and files from LMDB 0.9

LMDB 1.0 changed the on-disk format: it cannot open environments written by LMDB 0.9.x, and 0.9 cannot open 1.0 environments. natdb does not migrate data. Opening a 0.9 environment fails with Error::LegacyFormat and leaves its data file untouched (LMDB 1.0 reinitializes the lock file, which only holds transient reader state). Upstream's migration path (upgrading.doc) is to export with LMDB 0.9's mdb_dump and import with LMDB 1.0's mdb_load.

The new LMDB 1.0 capabilities (encryption and checksums, incremental backup, nested read-only transactions, two-phase commit, configurable page size) are declared in natdb-sys; the safe natdb API does not expose them yet.

Usage

use natdb::{Cursor, DatabaseFlags, Environment, Transaction, WriteFlags};

let env = Environment::new().set_max_dbs(4).open(path)?;
let db = env.create_db(Some("users"), DatabaseFlags::empty())?;

let mut txn = env.begin_rw_txn()?;
txn.put(db, b"user:1", b"Ada", WriteFlags::NO_OVERWRITE)?;
{
    // A savepoint: a nested transaction that is only durable with its parent.
    let mut nested = txn.begin_nested_txn()?;
    nested.put(db, b"user:2", b"Grace", WriteFlags::empty())?;
    nested.commit()?;
}
txn.commit()?;

let txn = env.begin_ro_txn()?;
let mut cursor = txn.open_ro_cursor(db)?;
for item in cursor.iter_start() {
    let (key, value) = item?;
    println!("{key:?} = {value:?}");
}

Read-write cursors read through RwCursor::reader(): the slices it returns keep the cursor mutably borrowed, so no write of the same transaction can modify the page they point to while they are alive.

Other additions over lmdb-rkv: natdb::version(), Environment::copy (plain or compacted backup of an open environment) and Error::LegacyFormat. See docs/triage.md for the outcome of every issue and pull request left open upstream.

Durability

natdb keeps LMDB's defaults: every commit is flushed to stable storage before it returns. On Apple platforms LMDB 1.0 uses fcntl(F_FULLFSYNC), which is slower than a plain fsync (about 8 ms per commit on an Apple Silicon SSD, versus 0.1 ms) but survives power loss. Group writes into one transaction to amortize it. EnvironmentFlags::NO_META_SYNC and NO_SYNC trade durability for speed and are opt-in.

Building

cargo build --workspace
cargo test --workspace

The minimum supported Rust version is 1.85 (edition 2024).

Optional natdb-sys features:

  • bindgen: regenerate natdb-sys/src/bindings.rs from lmdb.h. Needs a host libclang (LIBCLANG_PATH must not point to a cross-only clang): cargo build -p natdb-sys --features bindgen.
  • mdb_idl_logn_8 ... mdb_idl_logn_15: set MDB_IDL_LOGN, which sizes the free and dirty page lists (default 16). Mutually exclusive.

To build the C code with extra compiler flags (for example sanitizers), use the CFLAGS environment variable, which the cc crate honors.

Lineage

natdb is a maintained fork of Mozilla's lmdb-rkv, which is itself a fork of Dan Burkert's lmdb-rs. Mozilla's LMDB patches (mdb.RE/0.9.24-moz) are all part of upstream LMDB 1.0.2, so the vendored C sources are unmodified.

License

The Rust code is licensed under the Apache License 2.0; see NOTICE for attribution. The vendored LMDB sources are licensed under the OpenLDAP Public License 2.8.