MDBX Containers
Loading...
Searching...
No Matches
MDBX-Containers Library

Version: 1.0.0

Introduction

mdbx-containers bridges standard STL containers with high-performance libmdbx storage. It transparently persists data in a transactional database while exposing familiar container-like interfaces.

Key features:

  • Header-only usage or optional static library.
  • Unified API for KeyTable, KeyValueTable, and KeyMultiValueTable.
  • Automatic serialization of trivially copyable types and custom to_bytes()/from_bytes() support.
  • Multiple logical tables inside one MDBX environment.
  • Thread-safe operations with per-thread transactions.

Transactions

Every modifying operation runs inside a transaction. There are two ways to manage them:

  • RAII transactions created via Connection::transaction(). A transaction object commits on commit() or rolls back on destruction. Convenient for scoped writes.
  • Manual transactions started with Connection::begin() and finished with commit() or rollback(). This approach reduces overhead when grouping many operations.

Read transactions are reused per thread. Nested transactions are not supported.

Examples

Basic usage

mdbxc::Config cfg; // minimal config
cfg.pathname = "example.mdbx";
auto conn = mdbxc::Connection::create(cfg);
mdbxc::KeyValueTable<int, std::string> table(conn, "demo");
table.insert_or_assign(1, "one");
#if __cplusplus >= 201703L
std::optional<std::string> val = table.find(1);
if (val) std::cout << *val << std::endl;
#else
auto res = table.find_compat(1);
if (res.first) std::cout << res.second << std::endl;
#endif
mdbxc::Config
Parameters used by Connection to create the MDBX environment.
Definition Config.hpp:17
mdbxc::Config::pathname
std::string pathname
Path to the database file or directory containing the database.
Definition Config.hpp:19
mdbxc::Connection::create
static std::shared_ptr< Connection > create(const Config &config)
Creates and connects a new shared Connection instance.
Definition Connection.ipp:26
mdbxc::KeyValueTable
Template class for managing key-value pairs in an MDBX database.
Definition KeyValueTable.hpp:27

Manual transaction

mdbxc::Config cfg; cfg.pathname = "manual_txn.mdbx";
auto conn = mdbxc::Connection::create(cfg);
conn->begin(mdbxc::TransactionMode::WRITABLE);
mdbxc::KeyValueTable<int, std::string> tbl(conn, "data");
tbl.insert_or_assign(10, "ten");
conn->commit();
mdbxc::TransactionMode::WRITABLE
@ WRITABLE
Writable transaction (allows inserts, updates, deletes).
Definition Transaction.hpp:16

Multiple tables

mdbxc::Config cfg; cfg.pathname = "multi.mdbx"; cfg.max_dbs = 2;
auto conn = mdbxc::Connection::create(cfg);
mdbxc::KeyValueTable<int, std::string> a(conn, "numbers");
mdbxc::KeyValueTable<std::string, std::string> b(conn, "strings");
a.insert_or_assign(100, "hundred");
b.insert_or_assign("a", "b");
mdbxc::Config::max_dbs
int64_t max_dbs
Maximum number of named databases (DBI) in the environment.
Definition Config.hpp:27

Building

Use CMake or simply include the headers and link with libmdbx.

cmake -S . -B build -DBUILD_DEPS=ON -DBUILD_STATIC_LIB=ON
cmake --build build

For more details on container usage and C++ version differences see tables_page.

Configuration Guide

Details on tuning the MDBX environment are available on Database Configuration.

Repository

Sources: GitHub repository.

License

This project is licensed under the MIT License. It bundles libmdbx under the Apache License 2.0. See files in the repository for full texts.