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 ;
let env = new.set_max_dbs.open?;
let db = env.create_db?;
let mut txn = env.begin_rw_txn?;
txn.put?;
txn.commit?;
let txn = env.begin_ro_txn?;
let mut cursor = txn.open_ro_cursor?;
for item in cursor.iter_start
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
The minimum supported Rust version is 1.85 (edition 2024).
Optional natdb-sys features:
bindgen: regeneratenatdb-sys/src/bindings.rsfromlmdb.h. Needs a host libclang (LIBCLANG_PATHmust not point to a cross-only clang):cargo build -p natdb-sys --features bindgen.mdb_idl_logn_8...mdb_idl_logn_15: setMDB_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.