# natdb
Safe, idiomatic Rust bindings for the
[Lightning Memory-Mapped Database (LMDB)](https://www.symas.com/lmdb), built on
**LMDB 1.0.2**.
The workspace has two crates:
| `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/`](natdb-sys/lmdb/VENDORED.md); 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
```rust
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`](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
```bash
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](https://github.com/mozilla/lmdb-rs), which is itself a fork of Dan
Burkert's [lmdb-rs](https://github.com/danburkert/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](LICENSE); see
[NOTICE](NOTICE) for attribution. The vendored LMDB sources are licensed under
the [OpenLDAP Public License 2.8](natdb-sys/lmdb/LICENSE).