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 Definitions

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