API Reference¶

A C++20 module wrapper for the LMDB (Lightning Memory-Mapped Database) API.

namespace lmdbxx¶

Typedefs

using mode = mdb_mode_t¶: File creation mode type.

Enums

enum class env_flags : unsigned int¶

Environment configuration flags.

Values:

enumerator none¶: No special flags.

enumerator fixed_map¶: mmap at a fixed address (experimental).

enumerator no_subdir¶: No environment directory.

enumerator no_sync¶: Don’t fsync after commit.

enumerator rdonly¶: Read only.

enumerator no_meta_sync¶: Don’t fsync metapage after commit.

enumerator write_map¶: Use writable mmap.

enumerator map_async¶: Use asynchronous msync when MDB_WRITEMAP is used.

enumerator no_tls¶: Tie reader locktable slots to Txn objects instead of threads.

enumerator no_lock¶: Don’t do any locking.

enumerator no_readahead¶: Don’t do readahead.

enumerator no_mem_init¶: Don’t initialize malloc’d memory before writing to datafile.

enum class db_flags : unsigned int¶

Database open flags.

Values:

enumerator none¶: No special flags.

enumerator reverse_key¶: Use reverse string keys.

enumerator dupsort¶: Use sorted duplicates.

enumerator integer_key¶: Numeric keys in native byte order: either unsigned int or size_t.

enumerator dup_fixed¶: With MDB_DUPSORT, sorted dup items have fixed size.

enumerator integer_dup¶: With MDB_DUPSORT, dups are MDB_INTEGERKEY-style integers.

enumerator reverse_dup¶: With MDB_DUPSORT, use reverse string dups.

enumerator create¶: Create DB if not already existing.

enum class put_flags : unsigned int¶

Write flags for put operations.

Values:

enumerator none¶: No special flags.

enumerator no_overwrite¶: Enter new key/data pair only if it does not already appear.

enumerator no_dup_data¶: Enter new key/data pair only if it does not already appear in the database (MDB_DUPSORT only).

enumerator current¶: Overwrite the current key/data pair (MDB_DUPSORT only).

enumerator reserve¶: Just reserve space for data, don’t copy it. Return a pointer to the reserved space.

enumerator append¶: Data is being appended, don’t split full pages.

enumerator append_dup¶: Duplicate data is being appended, don’t split full pages.

enumerator multiple¶: Store multiple data items in one call.

enum class cursor_op : unsigned int¶

Cursor traversal operations.

Values:

enumerator first¶: Position at first key/data item.

enumerator first_dup¶: Position at first data item of current key. Only for MDB_DUPSORT.

enumerator get_both¶: Position at key/data pair. Only for MDB_DUPSORT.

enumerator get_both_range¶: position at key, nearest data. Only for MDB_DUPSORT.

enumerator get_current¶: Return key/data at current cursor position.

enumerator get_multiple¶: Return up to a page of duplicate data items from current cursor position.

enumerator last¶: Position at last key/data item.

enumerator last_dup¶: Position at last data item of current key. Only for MDB_DUPSORT.

enumerator next¶: Position at next data item.

enumerator next_dup¶: Position at next data item of current key. Only for MDB_DUPSORT.

enumerator next_multiple¶: Return up to a page of duplicate data items from next cursor position.

enumerator next_no_dup¶: Position at first data item of next key.

enumerator prev¶: Position at previous data item.

enumerator prev_dup¶: Position at previous data item of current key. Only for MDB_DUPSORT.

enumerator prev_no_dup¶: Position at last data item of previous key.

enumerator set¶: Position at specified key.

enumerator set_key¶: Position at specified key, return key + data.

enumerator set_range¶: Position at first key greater than or equal to specified key.

Functions

env_flags operator|(env_flags a, env_flags b)¶: Bitwise OR operator for env_flags.

env_flags operator&(env_flags a, env_flags b)¶: Bitwise AND operator for env_flags.

db_flags operator|(db_flags a, db_flags b)¶: Bitwise OR operator for db_flags.

db_flags operator&(db_flags a, db_flags b)¶: Bitwise AND operator for db_flags.

put_flags operator|(put_flags a, put_flags b)¶: Bitwise OR operator for put_flags.

put_flags operator&(put_flags a, put_flags b)¶: Bitwise AND operator for put_flags.

template<typename T> std::string_view ptr_to_sv(T *v)¶

Casts a pointer to a std::string_view representing its raw memory bytes.

Template Parameters:: T – The type being pointed to.
Parameters:: v – Pointer to the value.
Returns:: A std::string_view wrapping the pointer’s memory.

template<typename T> std::string_view to_sv(const T &v)¶

Casts a reference to a std::string_view representing its raw memory bytes.

Template Parameters:: T – The type of the value.
Parameters:: v – Reference to the value.
Returns:: A std::string_view wrapping the value’s memory.

template<typename T> T *ptr_from_sv(std::string_view v)¶

Recovers a pointer of type T from a std::string_view.

Template Parameters:: T – The desired type.
Parameters:: v – The string_view containing the bytes.
Throws:: runtime_error – if the string_view size doesn’t match sizeof(T).
Returns:: Pointer to T.

template<typename T> T from_sv(std::string_view v)¶

Copies memory from a std::string_view back into an object of type T.

Template Parameters:: T – The desired type.
Parameters:: v – The string_view containing the bytes.
Throws:: runtime_error – if the string_view size doesn’t match sizeof(T).
Returns:: A constructed instance of T containing the copied data.

class error : public std::runtime_error¶

Base exception class for LMDB errors.

Subclassed by lmdbxx::fatal_error, lmdbxx::logic_error, lmdbxx::runtime_error

Public Functions

inline error(const char *origin, int rc) noexcept¶

Constructor for LMDB error.

Parameters:

origin – The origin of the error.
rc – The LMDB return code.

inline int code() const noexcept¶

Retrieves the LMDB error code.

Returns:: The integer error code.

inline const char *origin() const noexcept¶

Retrieves the origin of the error.

Returns:: The origin string.

inline const char *what() const noexcept override¶

Returns the formatted error message.

Returns:: Formatted string containing the origin and the LMDB string representation of the error.

Public Static Functions

static void raise(const char *origin, int rc)¶

Raises the appropriate exception based on the LMDB return code.

Parameters:

origin – The name of the function where the error occurred.
rc – The LMDB return code.

Protected Attributes

const int _code¶

class logic_error : public lmdbxx::error ¶

for logic errors.

Public Functions

inline error(const char *origin, int rc) noexcept¶

Constructor for LMDB error.

Parameters:

origin – The origin of the error.
rc – The LMDB return code.

class fatal_error : public lmdbxx::error ¶

for fatal database errors.

Subclassed by lmdbxx::corrupted_error, lmdbxx::panic_error, lmdbxx::version_mismatch_error

Public Functions

inline error(const char *origin, int rc) noexcept¶

Constructor for LMDB error.

Parameters:

origin – The origin of the error.
rc – The LMDB return code.

class runtime_error : public lmdbxx::error ¶

for runtime errors.

Subclassed by lmdbxx::bad_dbi_error, lmdbxx::key_exist_error, lmdbxx::map_full_error, lmdbxx::not_found_error

Public Functions

inline error(const char *origin, int rc) noexcept¶

Constructor for LMDB error.

Parameters:

origin – The origin of the error.
rc – The LMDB return code.

class key_exist_error : public lmdbxx::runtime_error ¶: thrown when a key already exists.

class not_found_error : public lmdbxx::runtime_error ¶: thrown when a key/data pair is not found.

class corrupted_error : public lmdbxx::fatal_error ¶: thrown when the environment is corrupted.

class panic_error : public lmdbxx::fatal_error ¶: thrown for panic errors.

class version_mismatch_error : public lmdbxx::fatal_error ¶: thrown when there is a version mismatch.

class map_full_error : public lmdbxx::runtime_error ¶: thrown when the environment map size is reached.

class bad_dbi_error : public lmdbxx::runtime_error ¶: thrown for bad DBI handlers.

class env¶

RAII wrapper for MDB_env, representing an LMDB environment.

Public Functions

env() noexcept = default¶: Default constructor (creates an empty/null wrapper).

inline env(MDB_env *handle) noexcept¶

Constructs an env wrapper from an existing MDB_env handle.

*

Parameters:: handle – Raw MDB_env pointer.

inline env(env &&other) noexcept¶: Move constructor.

inline env &operator=(env &&other) noexcept¶: Move assignment operator.

inline ~env() noexcept¶: Destructor (closes the environment automatically).

inline operator MDB_env*() const noexcept¶: Conversion operator to underlying MDB_env*.

inline MDB_env *handle() const noexcept¶: Returns the underlying MDB_env handle.

inline void sync(bool force = true)¶

Flushes the data buffers to disk.

Parameters:: force – If true, force a synchronous flush.

inline void close() noexcept¶: Closes the environment and releases the memory map.

inline int reader_check()¶

Checks for stale entries in the reader lock table.

Returns:: Number of stale slots that were cleared.

inline env &open(const std::filesystem::path &path, env_flags flags = default_flags, mode mode = default_mode)¶

Opens an environment handle.

Parameters:

path – The directory in which the database files reside.
flags – Special options for this environment.
mode – The UNIX permissions to set on created files and semaphores.

Returns:

Reference to this env object.

inline env &set_flags(env_flags flags, bool onoff = true)¶

Sets environment flags.

Parameters:

flags – The flags to change.
onoff – A boolean indicating whether to set (true) or clear (false) the specified flags.

Returns:

Reference to this env object.

inline env &set_mapsize(std::size_t size)¶

Sets the size of the memory map to use for this environment.

Parameters:: size – The size in bytes.
Returns:: Reference to this env object.

inline env &set_max_readers(unsigned int count)¶

Sets the maximum number of threads/reader slots for the environment.

Parameters:: count – The maximum number of readers.
Returns:: Reference to this env object.

inline env &set_max_dbs(MDB_dbi count)¶

Sets the maximum number of named databases for the environment.

Parameters:: count – The maximum number of databases.
Returns:: Reference to this env object.

inline mdb_filehandle_t get_fd()¶

Gets the file descriptor for the environment.

Returns:: The underlying file descriptor.

inline std::string_view get_internal_map()¶

Gets the internal memory map pointer as a std::string_view.

Warning

Only supported on LP64 architectures.

Returns:: A std::string_view spanning the internal memory map.

Public Static Functions

static inline env create(env_flags flags = default_flags)¶

Creates a new LMDB environment.

Parameters:: flags – Optional flags for the environment creation.
Returns:: A newly created environment object.

Public Static Attributes

static env_flags default_flags = env_flags::none ¶

static mode default_mode = 0644¶

Protected Attributes

MDB_env *_handle = {nullptr}¶

class txn¶

RAII wrapper for MDB_txn, representing an LMDB transaction.

Public Functions

inline txn(MDB_txn *handle) noexcept¶

Constructs a txn wrapper from an existing MDB_txn handle.

*

Parameters:: handle – Raw MDB_txn pointer.

inline txn(txn &&other) noexcept¶: Move constructor.

inline txn &operator=(txn &&other) noexcept¶: Move assignment operator. Automatically aborts current transaction if active.

inline ~txn() noexcept¶: Destructor. Automatically aborts the transaction if it hasn’t been committed.

inline operator MDB_txn*() const noexcept¶: Conversion operator to underlying MDB_txn*.

inline MDB_txn *handle() const noexcept¶: Returns the underlying MDB_txn handle.

inline MDB_env *env() const noexcept¶: Returns the environment associated with the transaction.

inline void commit()¶: Commits all the operations of a transaction into the database.

Note

The transaction handle is freed and must not be used again.

inline void abort() noexcept¶: Aborts all operations of the transaction.

Note

The transaction handle is freed and must not be used again.

inline void reset() noexcept¶: Resets a read-only transaction.

Note

Aborts the transaction but keeps the handle so it can be renewed.

inline void renew()¶: Renews a read-only transaction.

Note

This acquires a new reader lock for a transaction that was previously reset.

Public Static Functions

static inline txn begin(MDB_env *env, MDB_txn *parent = nullptr, env_flags flags = default_flags)¶

Begins a new transaction.

Parameters:

env – The environment for the transaction.
parent – Optional parent transaction for nested transactions.
flags – Transaction flags (e.g., read-only).

Returns:

A new txn object.

Public Static Attributes

static env_flags default_flags = env_flags::none ¶

Protected Attributes

MDB_txn *_handle = {nullptr}¶

class dbi¶

Wrapper for MDB_dbi, representing an individual LMDB database handle.

Public Functions

dbi() noexcept = default¶: Default constructor.

inline dbi(MDB_dbi handle) noexcept¶

Constructs a dbi wrapper from an existing MDB_dbi handle.

Parameters:: handle – Raw MDB_dbi value.

~dbi() noexcept = default¶: Destructor.

inline operator MDB_dbi() const noexcept¶: Conversion operator to underlying MDB_dbi.

inline MDB_dbi handle() const noexcept¶: Returns the underlying MDB_dbi handle.

inline MDB_stat stat(MDB_txn *txn) const¶

Retrieves statistics for the database.

Parameters:: txn – The transaction context.
Returns:: The MDB_stat structure containing the statistics.

inline unsigned int flags(MDB_txn *txn) const¶

Retrieves the flags for the database.

Parameters:: txn – The transaction context.
Returns:: The flags integer.

inline std::size_t size(MDB_txn *txn) const¶

Gets the number of entries in the database.

Parameters:: txn – The transaction context.
Returns:: The number of entries.

inline void drop(MDB_txn *txn, bool del = false)¶

Empties or deletes and closes a database.

Parameters:

txn – The transaction context.
del – If true, delete the DB. If false, empty it but keep it open.

inline dbi &set_compare(MDB_txn *txn, MDB_cmp_func *cmp = nullptr)¶

Sets a custom key comparison function for a database.

Parameters:

txn – The transaction context.
cmp – The comparison function.

Returns:

Reference to this dbi object.

inline bool get(MDB_txn *txn, std::string_view key, std::string_view &data)¶

Gets items from a database.

Parameters:

txn – The transaction context.
key – The key to search for.
data – Reference to a string_view to populate with the retrieved data.

Returns:

True if successful, false if not found.

inline bool put(MDB_txn *txn, std::string_view key, std::string_view data, put_flags flags = default_put_flags)¶

Stores items into a database.

Parameters:

txn – The transaction context.
key – The key to store.
data – The data to store.
flags – Options for the put operation.

Returns:

True if successful, false if key exists (when no_overwrite is used).

inline bool del(MDB_txn *txn, std::string_view key)¶

Deletes items from a database.

Parameters:

txn – The transaction context.
key – The key to delete.

Returns:

True if deleted, false if not found.

inline bool del(MDB_txn *txn, std::string_view key, std::string_view val)¶

Deletes items from a database with duplicate matching.

Parameters:

txn – The transaction context.
key – The key to delete.
val – The specific data value to delete (for MDB_DUPSORT).

Returns:

True if deleted, false if not found.

Public Static Functions

static inline dbi open(MDB_txn *txn, const char *name = nullptr, db_flags flags = default_flags)¶

Opens a database in the environment.

Parameters:

txn – The transaction context.
name – The name of the database to open. If null, the default database is opened.
flags – Database open flags.

Returns:

A new dbi object.

static inline dbi open(MDB_txn *txn, std::string_view name, db_flags flags = default_flags)¶

Opens a database in the environment (std::string_view overload).

Parameters:

txn – The transaction context.
name – The name of the database to open.
flags – Database open flags.

Returns:

A new dbi object.

Public Static Attributes

static db_flags default_flags = db_flags::none ¶

static put_flags default_put_flags = put_flags::none ¶

Protected Attributes

MDB_dbi _handle = {(std::numeric_limits<MDB_dbi>::max)()}¶

class cursor¶

RAII wrapper for MDB_cursor, providing sequential database access.

Public Functions

inline cursor(MDB_cursor *handle) noexcept¶

Constructs a cursor wrapper from an existing MDB_cursor handle.

Parameters:: handle – Raw MDB_cursor pointer.

inline cursor(cursor &&other) noexcept¶: Move constructor.

inline cursor &operator=(cursor &&other) noexcept¶: Move assignment operator. Closes existing cursor before assignment.

inline ~cursor() noexcept¶: Destructor. Closes the cursor automatically.

inline operator MDB_cursor*() const noexcept¶: Conversion operator to underlying MDB_cursor*.

inline MDB_cursor *handle() const noexcept¶: Returns the underlying MDB_cursor handle.

inline void close() noexcept¶: Closes the cursor handle.

inline void renew(MDB_txn *txn)¶

Renews a cursor handle.

Parameters:: txn – The transaction context to renew under.

inline MDB_txn *txn() const noexcept¶

Returns the cursor’s transaction handle.

Returns:: MDB_txn pointer.

inline MDB_dbi dbi() const noexcept¶

Returns the cursor’s database handle.

Returns:: MDB_dbi identifier.

inline bool get(std::string_view &key, cursor_op op)¶

Retrieves a key from the database using a cursor operation.

Parameters:

key – Reference to a string_view to populate.
op – The cursor operation to execute.

Returns:

True if successful, false if not found.

inline bool get(std::string_view &key, std::string_view &val, cursor_op op)¶

Retrieves a key and data from the database using a cursor operation.

Parameters:

key – Reference to a string_view to populate with the key.
val – Reference to a string_view to populate with the value.
op – The cursor operation to execute.

Returns:

True if successful, false if not found.

inline bool put(std::string_view key, std::string_view val, put_flags flags = put_flags::none)¶

Stores a key/data pair using a cursor.

Parameters:

key – The key string_view.
val – The data string_view.
flags – Options for the put operation.

Returns:

True if successful, false if key/data exists.

inline void del(put_flags flags = put_flags::none)¶

Deletes the key/data pair currently positioned at by the cursor.

Parameters:: flags – Options for the delete operation.

inline std::size_t count()¶

Returns the count of duplicates for current key.

Returns:: The number of duplicates.

Public Static Functions

static inline cursor open(MDB_txn *txn, MDB_dbi dbi)¶

Creates a cursor handle.

Parameters:

txn – The transaction context.
dbi – The database handle.

Returns:

A new cursor object.

Protected Attributes

MDB_cursor *_handle = {nullptr}¶

API Reference¶

lmdbxx

Navigation

Related Topics