Expand description

Key-value database using LMDB

Caveats / Safety

Because of how memory-mapped I/O is being used and also because of certain assumptions of the underlying LMDB API, opening environments and databases requires unsafe Rust when using this library.

Do not open the same environment twice in the same process (see documentation of EnvBuilder). The file format is platform specific, so endianness and word size must not change across use.

When opening an already existing database, all options must be compatible with the previously used options (see documentation of DbOptions).

Stale readers might need to be cleared manually, see EnvRo::clear_stale_readers.

Example

use mmtkvdb::{self as kv, Txn as _};
use tempfile::tempdir;
fn doit() -> Result<(), std::io::Error> {
    let location = tempdir()?;
    let db1_opts = kv::DbOptions::new().name("db1");
    let db2_opts = kv::DbOptions::new().key_type::<str>().value_type::<i32>().name("db2");
    let env_builder = kv::EnvBuilder::new().dir(location.path()).max_dbs(2);
    {
        let mut env = unsafe { env_builder.open_rw()? };
        let db1 = unsafe { env.create_db(&db1_opts)? };
        let db2 = unsafe { env.create_db(&db2_opts)? };
        let mut txn = env.txn_rw()?;
        txn.put(&db1, "key1".as_bytes(), "value1".as_bytes())?;
        txn.put(&db2, "Prime", &17)?;
        txn.commit()?;
    }
    {
        let env = unsafe { env_builder.open_ro()? };
        let db1 = unsafe { env.open_db(&db1_opts)? };
        let db2 = unsafe { env.open_db(&db2_opts)? };
        let txn = env.txn_ro()?;
        assert_eq!(txn.get(&db1, "key1".as_bytes())?, Some("value1".as_bytes()));
        assert_eq!(txn.get_owned(&db2, "Prime")?, Some(17));
    }
    location.close()?;
    Ok(())
}
doit().expect("error during database access")

Re-exports

pub use owning_pointer::PointerIntoOwned;
pub use storable::Storable;

Modules

Some default values used for EnvBuilder

Bindings for LMDB library

Smart pointers owning their targets

Traits that are implemented for types that can be used as key or value

Structs

Cursor for reading from or writing to a particular database

Database handle

Options for opening a database

Options for opening an environment

Read-only handle for accessing environment that stores key-value databases

Read-write handle for accessing environment that stores key-value databases

Type argument to DbOptions and Db indicating non-unique keys

Type argument to DbOptions and Db indicating unique keys

Version of underlying LMDB library

Read-only transaction

Read-write transaction

Traits

Constraints on database (type argument C to DbOptions and Db)

Read-write or read-only transaction

Functions

Retrieve version of underlying LMDB library