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)](https://www.symas.com/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/`](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).