Template class for managing key-value pairs in an MDBX database. More...

#include <KeyValueTable.hpp>

Inheritance diagram for mdbxc::KeyValueTable< KeyT, ValueT >:

Classes
class	AssignmentProxy
	Helper proxy for convenient assignment via operator[]. More...

Public Member Functions
	KeyValueTable (std::shared_ptr< Connection > connection, std::string name="kv_store", MDBX_db_flags_t flags=MDBX_DB_DEFAULTS\|MDBX_CREATE)
	Default constructor.

	KeyValueTable (const Config &config, std::string name="kv_store", MDBX_db_flags_t flags=MDBX_DB_DEFAULTS\|MDBX_CREATE)
	Constructor with configuration.

	~KeyValueTable () override final=default
	Destructor.

template<template< class... > class ContainerT>
KeyValueTable &	operator= (const ContainerT< KeyT, ValueT > &container)
	Assigns a container (e.g., std::map or std::unordered_map) to the database.

KeyValueTable &	operator= (const std::vector< std::pair< KeyT, ValueT > > &container)
	Assigns a vector of key-value pairs to the database.

template<template< class... > class ContainerT = std::map>
auto	operator() ()
	Loads all key-value pairs from the database into a container.

AssignmentProxy	operator[] (const KeyT &key)
	Provides convenient access to insert or read a value by key.

template<template< class... > class ContainerT>
void	load (ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Loads data from the database into the container.

template<template< class... > class ContainerT>
void	load (ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Loads data from the database into the container using provided transaction.

void	load (std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Loads all key-value pairs into a std::vector of pairs.

void	load (std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Loads all key-value pairs into a std::vector of pairs.

template<template< class... > class ContainerT = std::map>
auto	retrieve_all (MDBX_txn *txn=nullptr)
	Retrieves all key-value pairs into the specified container type.

template<template< class... > class ContainerT = std::map>
auto	retrieve_all (const Transaction &txn)
	Retrieves all key-value pairs into the specified container type.

template<template< class... > class ContainerT>
void	append (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Appends data to the database.

template<template< class... > class ContainerT>
void	append (const ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Appends data to the database.

void	append (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Appends data from a vector to the database.

void	append (const std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Appends data from a vector to the database using a provided transaction.

template<template< class... > class ContainerT>
void	reconcile (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn=nullptr)
	Reconciles the database with the container.

template<template< class... > class ContainerT>
void	reconcile (const ContainerT< KeyT, ValueT > &container, const Transaction &txn)
	Reconciles the database with the container.

void	reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn=nullptr)
	Reconciles the database with the vector of key-value pairs.

void	reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, const Transaction &txn)
	Reconciles the database with the vector of key-value pairs using provided transaction.

bool	insert (const KeyT &key, const ValueT &value, MDBX_txn *txn=nullptr)
	Inserts key-value only if key is absent.

bool	insert (const KeyT &key, const ValueT &value, const Transaction &txn)
	Inserts key-value only if key is absent.

bool	insert (const std::pair< KeyT, ValueT > &pair, MDBX_txn *txn=nullptr)
	Inserts key-value only if key is absent.

bool	insert (const std::pair< KeyT, ValueT > &pair, const Transaction &txn)
	Inserts key-value only if key is absent.

void	insert_or_assign (const KeyT &key, const ValueT &value, MDBX_txn *txn=nullptr)
	Inserts or replaces key-value pair.

void	insert_or_assign (const KeyT &key, const ValueT &value, const Transaction &txn)
	Inserts or replaces key-value pair.

void	insert_or_assign (const std::pair< KeyT, ValueT > &pair, MDBX_txn *txn=nullptr)
	Inserts or replaces key-value pair.

void	insert_or_assign (const std::pair< KeyT, ValueT > &pair, const Transaction &txn)
	Inserts or replaces key-value pair.

ValueT	at (const KeyT &key, MDBX_txn *txn=nullptr) const
	Retrieves value by key or throws.

ValueT	at (const KeyT &key, const Transaction &txn) const
	Retrieves value by key or throws.

bool	try_get (const KeyT &key, ValueT &out, MDBX_txn *txn) const
	Tries to find value by key.

bool	try_get (const KeyT &key, ValueT &out, const Transaction &txn) const
	Tries to find value by key.

std::pair< bool, ValueT >	find_compat (const KeyT &key, MDBX_txn *txn=nullptr) const
	Finds value by key.

std::pair< bool, ValueT >	find_compat (const KeyT &key, const Transaction &txn) const
	Finds value by key.

bool	contains (const KeyT &key, MDBX_txn *txn=nullptr) const
	Checks whether a key exists in the database.

bool	contains (const KeyT &key, const Transaction &txn) const
	Checks whether a key exists in the database.

std::size_t	count (MDBX_txn *txn=nullptr) const
	Returns the number of elements in the database.

std::size_t	count (const Transaction &txn) const
	Returns the number of elements in the database.

bool	empty (MDBX_txn *txn=nullptr) const
	Checks if the database is empty.

bool	empty (const Transaction &txn) const
	Checks if the database is empty.

bool	erase (const KeyT &key, MDBX_txn *txn=nullptr)
	Removes key from DB.

bool	erase (const KeyT &key, const Transaction &txn)
	Removes key from DB.

void	clear (MDBX_txn *txn=nullptr)
	Clears all key-value pairs from the database.

void	clear (const Transaction &txn)
	Clears all key-value pairs from the database.

Public Member Functions inherited from mdbxc::BaseTable
	BaseTable (std::shared_ptr< Connection > connection, std::string name, MDBX_db_flags_t flags)
	Construct the database table accessor.

virtual	~BaseTable ()=default

bool	is_connected () const
	Checks if the connection is currently active.

void	connect ()
	Connects to the MDBX environment if not already connected.

void	disconnect ()
	Disconnects the MDBX environment.

void	begin (TransactionMode mode=TransactionMode::WRITABLE)
	Begins a manual transaction (must be committed or rolled back later).

void	commit ()
	Commits the current manual transaction.

void	rollback ()
	Rolls back the current manual transaction.

template<typename Func>
void	execute_in_transaction (Func operation, TransactionMode mode=TransactionMode::WRITABLE)
	Executes an operation inside an automatic transaction.

Private Member Functions
template<typename F>
void	with_transaction (F &&action, TransactionMode mode=TransactionMode::WRITABLE, MDBX_txn *txn=nullptr) const
	Executes a functor within a transaction context.

template<template< class... > class ContainerT>
void	db_load (ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Loads data from the database into the container.

void	db_load (std::vector< std::pair< KeyT, ValueT > > &out_vector, MDBX_txn *txn)
	Loads all key-value pairs into a std::vector of pairs.

bool	db_get (const KeyT &key, ValueT &value, MDBX_txn *txn_handle) const
	Gets a value by key from the database.

bool	db_contains (const KeyT &key, MDBX_txn *txn_handle) const
	Checks whether a key exists in the database.

std::size_t	db_count (MDBX_txn *txn_handle) const
	Returns the number of elements in the database.

template<template< class... > class ContainerT>
void	db_append (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Appends the content of the container to the database.

void	db_append (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn_handle)
	Appends the content of the vector to the database.

template<template< class... > class ContainerT>
void	db_reconcile (const ContainerT< KeyT, ValueT > &container, MDBX_txn *txn_handle)
	Reconciles the content of the database with the container.

void	db_reconcile (const std::vector< std::pair< KeyT, ValueT > > &container, MDBX_txn *txn_handle)
	Reconciles the content of the database with the given vector of key-value pairs.

bool	db_insert_if_absent (const KeyT &key, const ValueT &value, MDBX_txn *txn_handle)
	Inserts a key-value pair only if the key does not already exist.

void	db_insert_or_assign (const KeyT &key, const ValueT &value, MDBX_txn *txn_handle)
	Inserts or replaces the key-value pair.

bool	db_erase (const KeyT &key, MDBX_txn *txn_handle)
	Removes a key from the database.

void	db_clear (MDBX_txn *txn_handle)
	Clears all key-value pairs from the database.

Additional Inherited Members
Protected Member Functions inherited from mdbxc::BaseTable
MDBX_txn *	thread_txn () const
	Returns the transaction bound to the current thread, if any.

MDBX_dbi	handle () const
	Gets the raw DBI handle.

Protected Attributes inherited from mdbxc::BaseTable
std::shared_ptr< Connection >	m_connection
	Shared connection to MDBX environment.

MDBX_dbi	m_dbi {}
	DBI handle for the opened table.

Detailed Description

template<class KeyT, class ValueT>
class mdbxc::KeyValueTable< KeyT, ValueT >

Template class for managing key-value pairs in an MDBX database.

Template Parameters

KeyT	Type of the keys.
ValueT	Type of the values.

This class provides functionality to store, retrieve, and manipulate key-value pairs in an MDBX database. It supports various container types, such as std::map, std::unordered_map, std::vector, and std::list. Key-value pairs can be inserted, reconciled, retrieved, and removed with transaction support. The class includes methods for bulk loading and appending data with transactional integrity, ensuring that operations are safely executed in a database environment. Additionally, temporary tables are used during reconciliation to ensure consistent data synchronization. This class also provides methods for checking the count and emptiness of the database, and efficiently handles database errors with detailed exception handling.

Definition at line 27 of file KeyValueTable.hpp.

Constructor & Destructor Documentation

◆ KeyValueTable() [1/2]

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::KeyValueTable	(	std::shared_ptr< Connection >	connection,
		std::string	name = "kv_store",
		MDBX_db_flags_t	flags = MDBX_DB_DEFAULTS \| MDBX_CREATE )

inline

Default constructor.

Parameters

connection	Existing Connection instance.
name	Name of the table within the MDBX environment.
flags	Additional MDBX database flags.

Definition at line 34 of file KeyValueTable.hpp.

◆ KeyValueTable() [2/2]

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::KeyValueTable	(	const Config &	config,
		std::string	name = "kv_store",
		MDBX_db_flags_t	flags = MDBX_DB_DEFAULTS \| MDBX_CREATE )

inlineexplicit

Constructor with configuration.

Parameters

config	Configuration settings for the database.
name	Name of the table within the MDBX environment.
flags	Additional MDBX database flags.

Definition at line 45 of file KeyValueTable.hpp.

◆ ~KeyValueTable()

template<class KeyT, class ValueT>

mdbxc::KeyValueTable< KeyT, ValueT >::~KeyValueTable ( )

finaloverridedefault

Destructor.

Member Function Documentation

◆ append() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Appends data to the database.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container with content to be synchronized.
txn	Optional transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 230 of file KeyValueTable.hpp.

◆ append() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Appends data to the database.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container with content to be synchronized.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 218 of file KeyValueTable.hpp.

◆ append() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Appends data from a vector to the database using a provided transaction.

Parameters

container	Vector with content to be synchronized.
txn	Transaction wrapper.

Exceptions

MdbxException if a database error occurs.

Definition at line 249 of file KeyValueTable.hpp.

◆ append() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Appends data from a vector to the database.

Parameters

container	Vector with content to be synchronized.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 239 of file KeyValueTable.hpp.

◆ at() [1/2]

template<class KeyT, class ValueT>

ValueT mdbxc::KeyValueTable< KeyT, ValueT >::at	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Retrieves value by key or throws.

Parameters

key	The key to look up.
txn	Transaction wrapper used for the lookup.

Returns: The value associated with the key.

Exceptions

std::out_of_range	if key not found.
MdbxException	if DB error occurs.

Definition at line 399 of file KeyValueTable.hpp.

◆ at() [2/2]

template<class KeyT, class ValueT>

ValueT mdbxc::KeyValueTable< KeyT, ValueT >::at	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Retrieves value by key or throws.

Parameters

key	The key to look up.
txn	Active MDBX transaction.

Returns: The value associated with the key.

Exceptions

std::out_of_range	if key not found.
MdbxException	if DB error occurs.

Definition at line 383 of file KeyValueTable.hpp.

◆ clear() [1/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::clear ( const Transaction & txn )

inline

Clears all key-value pairs from the database.

Parameters

txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 574 of file KeyValueTable.hpp.

◆ clear() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::clear ( MDBX_txn * txn = nullptr )

inline

Clears all key-value pairs from the database.

Parameters

txn	Active transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 565 of file KeyValueTable.hpp.

◆ contains() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::contains	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Checks whether a key exists in the database.

Parameters

key	The key to look up.
txn	Transaction wrapper used for the lookup.

Returns: True if the key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 496 of file KeyValueTable.hpp.

◆ contains() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::contains	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Checks whether a key exists in the database.

Parameters

key	The key to look up.
txn	Active transaction.

Returns: True if the key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 483 of file KeyValueTable.hpp.

◆ count() [1/2]

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::count ( const Transaction & txn ) const

inline

Returns the number of elements in the database.

Parameters

txn	Transaction wrapper used for the count operation.

Returns: The number of key-value pairs.

Exceptions

MdbxException if DB error occurs.

Definition at line 516 of file KeyValueTable.hpp.

◆ count() [2/2]

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::count ( MDBX_txn * txn = nullptr ) const

inline

Returns the number of elements in the database.

Parameters

txn	Active transaction.

Returns: The number of key-value pairs.

Exceptions

MdbxException if DB error occurs.

Definition at line 504 of file KeyValueTable.hpp.

◆ db_append() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_append	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Appends the content of the container to the database.

Template Parameters

ContainerT Template for the container type (map or unordered_map).

Parameters

container	Container with content to append.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 696 of file KeyValueTable.hpp.

◆ db_append() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_append	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Appends the content of the vector to the database.

Parameters

container	Vector with key-value pairs to append.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 711 of file KeyValueTable.hpp.

◆ db_clear()

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_clear ( MDBX_txn * txn_handle )

inlineprivate

Clears all key-value pairs from the database.

Exceptions

MdbxException if an MDBX error occurs.

Definition at line 845 of file KeyValueTable.hpp.

◆ db_contains()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_contains	(	const KeyT &	key,
		MDBX_txn *	txn_handle ) const

inlineprivate

Checks whether a key exists in the database.

Parameters

key	The key to check.
txn_handle	The active transaction.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 671 of file KeyValueTable.hpp.

◆ db_count()

template<class KeyT, class ValueT>

std::size_t mdbxc::KeyValueTable< KeyT, ValueT >::db_count ( MDBX_txn * txn_handle ) const

inlineprivate

Returns the number of elements in the database.

Parameters

txn_handle Active transaction handle.

Returns: The number of key-value pairs in the database.

Exceptions

MdbxException if a database error occurs.

Definition at line 684 of file KeyValueTable.hpp.

◆ db_erase()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_erase	(	const KeyT &	key,
		MDBX_txn *	txn_handle )

inlineprivate

Removes a key from the database.

Parameters

key	The key of the pair to be removed.
txn_handle	The active MDBX transaction.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails for other reasons.

Definition at line 834 of file KeyValueTable.hpp.

◆ db_get()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_get	(	const KeyT &	key,
		ValueT &	value,
		MDBX_txn *	txn_handle ) const

inlineprivate

Gets a value by key from the database.

Parameters

key	The key to search for.
value	Reference to store the retrieved value.
txn_handle	The active transaction.

Returns: True if found, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 656 of file KeyValueTable.hpp.

◆ db_insert_if_absent()

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::db_insert_if_absent	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn_handle )

inlineprivate

Inserts a key-value pair only if the key does not already exist.

Parameters

key	The key to insert.
value	The value to insert.
txn_handle	The active MDBX transaction.

Returns: true if the key-value pair was inserted, false if the key already existed.

Exceptions

MdbxException if the insert fails for reasons other than key existence.

Definition at line 801 of file KeyValueTable.hpp.

◆ db_insert_or_assign()

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn_handle )

inlineprivate

Inserts or replaces the key-value pair.

Parameters

key	The key to insert or replace.
value	The value to set.
txn_handle	The active MDBX transaction.

Exceptions

MdbxException if the operation fails.

Definition at line 820 of file KeyValueTable.hpp.

◆ db_load() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_load	(	ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Loads data from the database into the container.

Template Parameters

ContainerT Template for the container type.

Parameters

container	Container to be synchronized with database content.
txn_handle	Active transaction handle.

Exceptions

MdbxException if a database error occurs.

Definition at line 618 of file KeyValueTable.hpp.

◆ db_load() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_load	(	std::vector< std::pair< KeyT, ValueT > > &	out_vector,
		MDBX_txn *	txn )

inlineprivate

Loads all key-value pairs into a std::vector of pairs.

Parameters

out_vector	The output vector to fill.
txn	Optional transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 636 of file KeyValueTable.hpp.

◆ db_reconcile() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Reconciles the content of the database with the container.

Synchronizes the main table with the content of the container by using a temporary table. Clears old data, inserts new data, and updates existing records in the main table.

Template Parameters

ContainerT Template for the container type (map or unordered_map).

Parameters

container	Container with key-value pairs to be reconciled with the database.
txn_handle	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 730 of file KeyValueTable.hpp.

◆ db_reconcile() [2/2]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::db_reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn_handle )

inlineprivate

Reconciles the content of the database with the given vector of key-value pairs.

Clears existing records not present in the vector, and upserts all from the vector.

Parameters

container	Vector of key-value pairs to reconcile with the database.
txn_handle	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 763 of file KeyValueTable.hpp.

◆ empty() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::empty ( const Transaction & txn ) const

inline

Checks if the database is empty.

Parameters

txn	Transaction wrapper used for the check.

Returns: True if the database is empty, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 536 of file KeyValueTable.hpp.

◆ empty() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::empty ( MDBX_txn * txn = nullptr ) const

inline

Checks if the database is empty.

Parameters

txn	Optional transaction handle.

Returns: True if the database is empty, false otherwise.

Exceptions

MdbxException if a database error occurs.

Definition at line 524 of file KeyValueTable.hpp.

◆ erase() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::erase	(	const KeyT &	key,
		const Transaction &	txn )

inline

Removes key from DB.

Parameters

key	The key of the pair to be removed.
txn	Transaction wrapper used for the operation.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails.

Definition at line 558 of file KeyValueTable.hpp.

◆ erase() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::erase	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr )

inline

Removes key from DB.

Parameters

key	The key of the pair to be removed.
txn	Active transaction.

Returns: True if the key was found and deleted, false if the key was not found.

Exceptions

MdbxException if deletion fails.

Definition at line 545 of file KeyValueTable.hpp.

◆ find_compat() [1/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find_compat	(	const KeyT &	key,
		const Transaction &	txn ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Transaction wrapper used for the lookup.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 474 of file KeyValueTable.hpp.

◆ find_compat() [2/2]

template<class KeyT, class ValueT>

std::pair< bool, ValueT > mdbxc::KeyValueTable< KeyT, ValueT >::find_compat	(	const KeyT &	key,
		MDBX_txn *	txn = nullptr ) const

inline

Finds value by key.

Parameters

key	Key to search for.
txn	Optional active MDBX transaction.

Returns: Pair of success flag and value.

Exceptions

MdbxException on DB error.

Definition at line 459 of file KeyValueTable.hpp.

◆ insert() [1/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const KeyT &	key,
		const ValueT &	value,
		const Transaction &	txn )

inline

Inserts key-value only if key is absent.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Transaction wrapper used for the insertion.

Returns

Exceptions

MdbxException if a database error occurs.

Definition at line 313 of file KeyValueTable.hpp.

◆ insert() [2/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn = nullptr )

inline

Inserts key-value only if key is absent.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Active MDBX transaction.

Returns

Exceptions

MdbxException if a database error occurs.

Definition at line 299 of file KeyValueTable.hpp.

◆ insert() [3/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const std::pair< KeyT, ValueT > &	pair,
		const Transaction &	txn )

inline

Inserts key-value only if key is absent.

Parameters

pair	The key-value pair to be inserted.
txn	Transaction wrapper used for the operation.

Returns

Exceptions

MdbxException if a database error occurs.

Definition at line 335 of file KeyValueTable.hpp.

◆ insert() [4/4]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::insert	(	const std::pair< KeyT, ValueT > &	pair,
		MDBX_txn *	txn = nullptr )

inline

Inserts key-value only if key is absent.

Parameters

pair	The key-value pair to be inserted.
txn	Active MDBX transaction.

Returns

Exceptions

MdbxException if a database error occurs.

Definition at line 322 of file KeyValueTable.hpp.

◆ insert_or_assign() [1/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		const Transaction &	txn )

inline

Inserts or replaces key-value pair.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 355 of file KeyValueTable.hpp.

◆ insert_or_assign() [2/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const KeyT &	key,
		const ValueT &	value,
		MDBX_txn *	txn = nullptr )

inline

Inserts or replaces key-value pair.

Parameters

key	The key to be inserted.
value	The value to be inserted.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 344 of file KeyValueTable.hpp.

◆ insert_or_assign() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const std::pair< KeyT, ValueT > &	pair,
		const Transaction &	txn )

inline

Inserts or replaces key-value pair.

Parameters

pair	The key-value pair to be inserted.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 373 of file KeyValueTable.hpp.

◆ insert_or_assign() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::insert_or_assign	(	const std::pair< KeyT, ValueT > &	pair,
		MDBX_txn *	txn = nullptr )

inline

Inserts or replaces key-value pair.

Parameters

pair	The key-value pair to be inserted.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 363 of file KeyValueTable.hpp.

◆ load() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Loads data from the database into the container using provided transaction.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 160 of file KeyValueTable.hpp.

◆ load() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Loads data from the database into the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be synchronized with database content.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 148 of file KeyValueTable.hpp.

◆ load() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Loads all key-value pairs into a std::vector of pairs.

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 178 of file KeyValueTable.hpp.

◆ load() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::load	(	std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Loads all key-value pairs into a std::vector of pairs.

Parameters

container	Container to be synchronized with database content.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 168 of file KeyValueTable.hpp.

◆ operator()()

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

auto mdbxc::KeyValueTable< KeyT, ValueT >::operator() ( )

inline

Loads all key-value pairs from the database into a container.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 87 of file KeyValueTable.hpp.

◆ operator=() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

KeyValueTable & mdbxc::KeyValueTable< KeyT, ValueT >::operator= ( const ContainerT< KeyT, ValueT > & container )

inline

Assigns a container (e.g., std::map or std::unordered_map) to the database.

Parameters

container The container with key-value pairs.

Returns: Reference to this KeyValueTable.

Exceptions

MdbxException if a database error occurs.

Note: The transaction mode is taken from the database configuration.

Definition at line 63 of file KeyValueTable.hpp.

◆ operator=() [2/2]

template<class KeyT, class ValueT>

KeyValueTable & mdbxc::KeyValueTable< KeyT, ValueT >::operator= ( const std::vector< std::pair< KeyT, ValueT > > & container )

inline

Assigns a vector of key-value pairs to the database.

Parameters

container The vector with key-value pairs.

Returns: Reference to this KeyValueTable.

Exceptions

MdbxException if a database error occurs.

Note: The transaction mode is taken from the database configuration.

Definition at line 75 of file KeyValueTable.hpp.

◆ operator[]()

template<class KeyT, class ValueT>

AssignmentProxy mdbxc::KeyValueTable< KeyT, ValueT >::operator[] ( const KeyT & key )

inline

Provides convenient access to insert or read a value by key.

Parameters

key	Key to access.

Returns: Proxy object used for assignment or implicit read.

Definition at line 136 of file KeyValueTable.hpp.

◆ reconcile() [1/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		const Transaction &	txn )

inline

Reconciles the database with the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be reconciled with the database.
txn	Transaction wrapper used for the operation.

Exceptions

MdbxException if a database error occurs.

Definition at line 271 of file KeyValueTable.hpp.

◆ reconcile() [2/4]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const ContainerT< KeyT, ValueT > &	container,
		MDBX_txn *	txn = nullptr )

inline

Reconciles the database with the container.

Template Parameters

ContainerT Container type (e.g., std::map or std::unordered_map).

Parameters

container	Container to be reconciled with the database.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 259 of file KeyValueTable.hpp.

◆ reconcile() [3/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		const Transaction &	txn )

inline

Reconciles the database with the vector of key-value pairs using provided transaction.

Parameters

container	Vector to be reconciled with the database.
txn	Transaction wrapper.

Exceptions

MdbxException if a database error occurs.

Definition at line 289 of file KeyValueTable.hpp.

◆ reconcile() [4/4]

template<class KeyT, class ValueT>

void mdbxc::KeyValueTable< KeyT, ValueT >::reconcile	(	const std::vector< std::pair< KeyT, ValueT > > &	container,
		MDBX_txn *	txn = nullptr )

inline

Reconciles the database with the vector of key-value pairs.

Parameters

container	Vector to be reconciled with the database.
txn	Active MDBX transaction.

Exceptions

MdbxException if a database error occurs.

Definition at line 279 of file KeyValueTable.hpp.

◆ retrieve_all() [1/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

auto mdbxc::KeyValueTable< KeyT, ValueT >::retrieve_all ( const Transaction & txn )

inline

Retrieves all key-value pairs into the specified container type.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Parameters

txn	Transaction wrapper used for the retrieval.

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 208 of file KeyValueTable.hpp.

◆ retrieve_all() [2/2]

template<class KeyT, class ValueT>

template<template< class... > class ContainerT = std::map>

auto mdbxc::KeyValueTable< KeyT, ValueT >::retrieve_all ( MDBX_txn * txn = nullptr )

inline

Retrieves all key-value pairs into the specified container type.

Template Parameters

ContainerT Container type (e.g., std::map, std::unordered_map, std::vector).

Parameters

txn	Optional transaction handle.

Returns: Filled container.

Exceptions

MdbxException if a database error occurs.

Definition at line 188 of file KeyValueTable.hpp.

◆ try_get() [1/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::try_get	(	const KeyT &	key,
		ValueT &	out,
		const Transaction &	txn ) const

inline

Tries to find value by key.

Parameters

key	The key to look up.
out	Reference to output value.
txn	Transaction wrapper used for the lookup.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 423 of file KeyValueTable.hpp.

◆ try_get() [2/2]

template<class KeyT, class ValueT>

bool mdbxc::KeyValueTable< KeyT, ValueT >::try_get	(	const KeyT &	key,
		ValueT &	out,
		MDBX_txn *	txn ) const

inline

Tries to find value by key.

Parameters

key	The key to look up.
out	Reference to output value.
txn	Active MDBX transaction.

Returns: True if key exists, false otherwise.

Exceptions

MdbxException if DB error occurs.

Definition at line 409 of file KeyValueTable.hpp.

◆ with_transaction()

template<class KeyT, class ValueT>

template<typename F>

void mdbxc::KeyValueTable< KeyT, ValueT >::with_transaction	(	F &&	action,
		TransactionMode	mode = TransactionMode::WRITABLE,
		MDBX_txn *	txn = nullptr ) const

inlineprivate

Executes a functor within a transaction context.

Template Parameters

F	Callable type accepting `MDBX_txn*`.

Parameters

action	Functor to execute.
mode	Transaction mode used when a new transaction is created.
txn	Optional existing transaction handle.

Definition at line 586 of file KeyValueTable.hpp.

The documentation for this class was generated from the following file:

include/mdbx_containers/KeyValueTable.hpp

Classes

Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ KeyValueTable() [1/2]

◆ KeyValueTable() [2/2]

◆ ~KeyValueTable()

Member Function Documentation

◆ append() [1/4]

◆ append() [2/4]

◆ append() [3/4]

◆ append() [4/4]

◆ at() [1/2]

◆ at() [2/2]

◆ clear() [1/2]

◆ clear() [2/2]

◆ contains() [1/2]

◆ contains() [2/2]

◆ count() [1/2]

◆ count() [2/2]

◆ db_append() [1/2]

◆ db_append() [2/2]

◆ db_clear()

◆ db_contains()

◆ db_count()

◆ db_erase()

◆ db_get()

◆ db_insert_if_absent()

◆ db_insert_or_assign()

◆ db_load() [1/2]

◆ db_load() [2/2]

◆ db_reconcile() [1/2]

◆ db_reconcile() [2/2]

◆ empty() [1/2]

◆ empty() [2/2]

◆ erase() [1/2]

◆ erase() [2/2]

◆ find_compat() [1/2]

◆ find_compat() [2/2]

◆ insert() [1/4]

◆ insert() [2/4]

◆ insert() [3/4]

◆ insert() [4/4]

◆ insert_or_assign() [1/4]

◆ insert_or_assign() [2/4]

◆ insert_or_assign() [3/4]

◆ insert_or_assign() [4/4]

◆ load() [1/4]

◆ load() [2/4]

◆ load() [3/4]

◆ load() [4/4]

◆ operator()()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ reconcile() [1/4]

◆ reconcile() [2/4]

◆ reconcile() [3/4]

◆ reconcile() [4/4]

◆ retrieve_all() [1/2]

◆ retrieve_all() [2/2]

◆ try_get() [1/2]

◆ try_get() [2/2]

◆ with_transaction()