Crate mmtkvdb

source ·
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 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

Modules

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 DbBuilder and Db indicating non-unique keys
  • Type argument to DbBuilder and Db indicating unique keys
  • Version of underlying LMDB library
  • Wrapper akin to Cow::Owned but known to be owned at compile-time
  • Read-only transaction
  • Read-write transaction

Traits

  • Constraints on database (type argument C to DbBuilder and Db)
  • Read-write or read-only handle for accessing environment that stores key-value databases
  • Abstraction over &EnvRo and &mut EnvRw, which allows creating databases in the latter case if non-existing
  • Generalized Cow
  • Read-write or read-only transaction

Functions

Type Definitions

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