Crate mmtkvdb 

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 at the same time (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 DbBuilder).

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

Example

// question mark operator may return with `std::io::Error`
use mmtkvdb::{self as kv, traits::*};
use tempfile::tempdir;
let location = tempdir()?;
let db1_opts = kv::DbBuilder::new().name("db1");
let db2_opts = kv::DbBuilder::new().key_type::<str>().value_type::<i32>().name("db2");
let env_builder = kv::EnvBuilder::new().dir(location.path()).max_dbs(2);
{
    // SAFETY:
    // * database isn't opened twice in this process at the same time
    // * it is assumed no other processes access the environment
    // * since environment is newly created, it matches the platform
    let mut env = unsafe { env_builder.open_rw()? };
    // SAFETY: database doesn't exist yet (or would need compatible options)
    let db1 = unsafe { env.create_db(&db1_opts)? };
    // SAFETY: database doesn't exist yet (or would need compatible options)
    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()?;
}
{
    // SAFETY:
    // * database isn't opened twice in this process at the same time
    // * it is assumed no other processes access the environment
    // * the environment has been created above, thus it matches the platform
    let env = unsafe { env_builder.open_ro()? };
    // SAFETY: database options are compatible with the ones used when
    // creating the database
    let db1 = unsafe { env.open_db(&db1_opts)? };
    // SAFETY: database options are compatible with the ones used when
    // creating the database
    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()?;

Re-exports

pub use storable::BorrowStorable;

pub use storable::NoKey;

pub use storable::NoValue;

pub use storable::Storable;

pub use storable::StorableConstBytesLen;

pub use storable::StorableRef;

Modules

cow

Generalization of Cow

env_builder_defaults

Some default values used for EnvBuilder

lmdb

Bindings for LMDB library

storable

Traits allowing to use types as key or value

traits

Important traits re-exported without name

Structs

Cursor

Cursor for reading from or writing to a particular database

Db

Database handle

DbBuilder

Options for opening a database

EnvBuilder

Options for opening an environment

EnvRo

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

EnvRw

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

KeysDuplicate

Type argument to DbBuilder and Db indicating non-unique keys

KeysUnique

Type argument to DbBuilder and Db indicating unique keys

LmdbVersion

Version of underlying LMDB library

Owned

Wrapper akin to Cow::Owned but known to be owned at compile-time

TxnRo

Read-only transaction

TxnRw

Read-write transaction

Traits

Constraint

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

Env

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

EnvRef

Abstraction over &EnvRo and &mut EnvRw, which allows creating databases in the latter case if non-existing

GenericCow

Generalized Cow

Txn

Read-write or read-only transaction

Functions

lmdb_version

Retrieve version of underlying LMDB library

Type Aliases

DbSpec

Type alias for DbBuilder which has a name set (or unnamed database selected)