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-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
• 2023-03-07: Version 0.13.0
  • Added various cursor methods to Txn trait, which allow moving cursors without retrieving data
  • Removed deprecated implementation of Storable for () (use NoKey and/or NoValue instead of ())
• 2023-03-06: Version 0.12.1
  • Removed dependencies on unstable Rust features
  • Introduced NoKey and NoValue unit structs to replace () as type for databases which have no key or no value, respectively (this deprecates the implementation of Storable for ())
  • Added method which deletes all entries in database
  • New method TxnRw::on_commit allows registering a closure that will be executed on Txn::commit before the transaction is actually committed

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