mmtkvdb

mmtkvdb is a crate for Rust which provides a memory-mapped key-value database. It uses LMDB and links with an existing liblmdb on the system.

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 (i.e. the programmer must ensure that certain preconditions are met that cannot be enforced by the compiler to avoid undefined behavior). If you aim to program in safe Rust only, this Rust library is not suitable for you.

API Documentation

For documentation on how to use this crate, refer to the example in src/lib.rs.

License

See contained LICENSE file (MIT License).

Changelog

• 2023-03-20: Version 0.16.0
  • Documented that Storable::cmp_bytes_unchecked of the unsafe Storable trait must never unwind (as this might leave the LMDB environment in an invalid state)
  • Removed ToOwned bound from Storable trait because it was not needed
  • Methods nosync, mapasync, and nordahead as well as corresponding getter methods have been added to EnvBuilder to allow better configuration of the environment
  • Minor performance improvements
    • Avoid unnecessary upgrading of a Weak by storing a unique identifier of the environment in each DbBackend
    • Replaced mutex CursorBackend::closed with an AtomicBool using Relaxed loads and stores to increase performance (free/malloc performs the necessary synchronization)
  • Minor documentation improvements
  • Code cleanup in benchmark and changed some benchmark settings
• 2023-03-17: Version 0.15.0
  • Several deprecated items have been removed:
    • DbOptions
    • Env::open_dbs
    • EnvRw::create_dbs
    • EnvRef::open_or_create_dbs
    • Txn::cursor_search_key_get_key
  • EnvRw::drop_db requires &mut self
  • Env::clear_stale_readers returns std::io::Result<usize>
  • Improved documentation in regard to use of unsafe
• 2023-03-16: Version 0.14.1
  • Critical bug fixes:
    • Opening the same database twice (in the same process) might have caused UB. This has been fixed.
    • LMDB databases might have been closed twice if an error occurred during opening, which might have caused UB in that case. This has been fixed.
    • Method Txn::cursor_get_current_value_count must only be called for databases with KeysDuplicate. This is enforced by the methods signature now and could have been resulting in UB previously.
    • A memory leak in EnvRw::drop_db has been fixed and code has been cleaned up and properly documented to avoid this in the future.
    • Write transactions which created a cursor but never wrote any data might have resulted in mdb_cursor_close being called after mdb_dbi_close, which is not allowed for write transaction by LMDB's API specification. This has been fixed.
  • All LMDB databases get closed explicitly now before the LMDB environment is closed.
  • Missing implementations for Send and Sync have been added for EnvRo, EnvRw, Db, and Cursor.
  • Deprecations:
    • A warning has been added to the documentation, stating that EnvRw::drop_db will require &mut self in future.
    • Methods for opening several databases at once (with the same types) have been deprecated. The methods opening a single database should be used instead.
  • Improved "Safety" sections in public API documentation
  • Code cleanup in regard to safety:
    • Use unsafe_op_in_unsafe_fn lint and added corresponding unsafe blocks
    • Added SAFETY comments in src/lib.rs
    • Correctly marked some private functions as unsafe and documented their use properly
• 2023-03-10: Version 0.14.0
  • TxnRo is now !Sync (but still Send); users are expected to use a mutex where synchronization is required
  • Deprecated Txn::cursor_search_key_get_key
  • Improved documentation regarding return values of cursor methods
  • Added benchmarks

For older changes, refer to the CHANGELOG.md file.