Tables

Typedefs
typedef uint32_t	MDBX_dbi
	A handle for an individual table (key-value spaces) in the environment.

Enumerations
enum	MDBX_db_flags_t {   MDBX_DB_DEFAULTS = 0 , MDBX_REVERSEKEY = UINT32_C(0x02) , MDBX_DUPSORT = UINT32_C(0x04) , MDBX_INTEGERKEY = UINT32_C(0x08) ,   MDBX_DUPFIXED = UINT32_C(0x10) , MDBX_INTEGERDUP = UINT32_C(0x20) , MDBX_REVERSEDUP = UINT32_C(0x40) , MDBX_CREATE = UINT32_C(0x40000) ,   MDBX_DB_ACCEDE = MDBX_ACCEDE }
	Table flags. More...

Functions
LIBMDBX_API int	mdbx_dbi_open (MDBX_txn *txn, const char *name, MDBX_db_flags_t flags, MDBX_dbi *dbi)
	Open or Create a named table in the environment.
LIBMDBX_API int	mdbx_dbi_open2 (MDBX_txn *txn, const MDBX_val *name, MDBX_db_flags_t flags, MDBX_dbi *dbi)
	Open or Create a named table in the environment.
LIBMDBX_API int	mdbx_dbi_open_ex (MDBX_txn *txn, const char *name, MDBX_db_flags_t flags, MDBX_dbi *dbi, MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp)
	Open or Create a named table in the environment with using custom comparison functions.
LIBMDBX_API int	mdbx_dbi_open_ex2 (MDBX_txn *txn, const MDBX_val *name, MDBX_db_flags_t flags, MDBX_dbi *dbi, MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp)
	Open or Create a named table in the environment with using custom comparison functions.
LIBMDBX_API int	mdbx_dbi_rename (MDBX_txn *txn, MDBX_dbi dbi, const char *name)
	Переименовает таблицу по DBI-дескриптору
LIBMDBX_API int	mdbx_dbi_rename2 (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *name)
	Переименовает таблицу по DBI-дескриптору
LIBMDBX_API int	mdbx_dbi_close (MDBX_env *env, MDBX_dbi dbi)
	Close a table handle. Normally unnecessary.

Detailed Description

Typedef Documentation

MDBX_dbi

typedef uint32_t MDBX_dbi

A handle for an individual table (key-value spaces) in the environment.

Zero handle is used internally (hidden Garbage Collection table). So, any valid DBI-handle great than 0 and less than or equal MDBX_MAX_DBI.

See also

mdbx_dbi_open()

mdbx_dbi_close()

Enumeration Type Documentation

MDBX_db_flags_t

enum MDBX_db_flags_t

Table flags.

See also

mdbx_dbi_open()

Enumerator
MDBX_DB_DEFAULTS	Variable length unique keys with usual byte-by-byte string comparison.
MDBX_REVERSEKEY	Use reverse string comparison for keys.
MDBX_DUPSORT	Use sorted duplicates, i.e. allow multi-values for a keys.
MDBX_INTEGERKEY	Numeric keys in native byte order either uint32_t or uint64_t (must be one of uint32_t or uint64_t, other integer types, for example, signed integer or uint16_t will not work). The keys must all be of the same size and must be aligned while passing as arguments.
MDBX_DUPFIXED	With MDBX_DUPSORT; sorted dup items have fixed size. The data values must all be of the same size.
MDBX_INTEGERDUP	With MDBX_DUPSORT and with MDBX_DUPFIXED; dups are fixed size like MDBX_INTEGERKEY -style integers. The data values must all be of the same size and must be aligned while passing as arguments.
MDBX_REVERSEDUP	With MDBX_DUPSORT; use reverse string comparison for data values.
MDBX_CREATE	Create DB if not already existing.
MDBX_DB_ACCEDE	Opens an existing table created with unknown flags. The MDBX_DB_ACCEDE flag is intend to open a existing table which was created with unknown flags (MDBX_REVERSEKEY, MDBX_DUPSORT, MDBX_INTEGERKEY, MDBX_DUPFIXED, MDBX_INTEGERDUP and MDBX_REVERSEDUP). In such cases, instead of returning the MDBX_INCOMPATIBLE error, the table will be opened with flags which it was created, and then an application could determine the actual flags by mdbx_dbi_flags().

Function Documentation

mdbx_dbi_close()

LIBMDBX_API int mdbx_dbi_close	(	MDBX_env *	env,
		MDBX_dbi	dbi
	)

Close a table handle. Normally unnecessary.

Closing a table handle is not necessary, but lets mdbx_dbi_open() reuse the handle value. Usually it's better to set a bigger mdbx_env_set_maxdbs(), unless that value would be large.

Note

Use with care. This call is synchronized via mutex with mdbx_dbi_open(), but NOT with any transaction(s) running by other thread(s). So the mdbx_dbi_close() MUST NOT be called in-parallel/concurrently with any transactions using the closing dbi-handle, nor during other thread commit/abort a write transacton(s). The "next" version of libmdbx (MithrilDB and Future) will solve this issue.

Handles should only be closed if no other threads are going to reference the table handle or one of its cursors any further. Do not close a handle if an existing transaction has modified its table. Doing so can cause misbehavior from table corruption to errors like MDBX_BAD_DBI (since the DB name is gone).

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	dbi	A table handle returned by mdbx_dbi_open().

Returns

A non-zero error value on failure and 0 on success.

mdbx_dbi_open()

LIBMDBX_API int mdbx_dbi_open	(	MDBX_txn *	txn,
		const char *	name,
		MDBX_db_flags_t	flags,
		MDBX_dbi *	dbi
	)

Open or Create a named table in the environment.

A table handle denotes the name and parameters of a table, independently of whether such a table exists. The table handle may be discarded by calling mdbx_dbi_close(). The old table handle is returned if the table was already open. The handle may only be closed once.

Note

A notable difference between MDBX and LMDB is that MDBX make handles opened for existing tables immediately available for other transactions, regardless this transaction will be aborted or reset. The REASON for this is to avoiding the requirement for multiple opening a same handles in concurrent read transactions, and tracking of such open but hidden handles until the completion of read transactions which opened them.

Nevertheless, the handle for the NEWLY CREATED table will be invisible for other transactions until the this write transaction is successfully committed. If the write transaction is aborted the handle will be closed automatically. After a successful commit the such handle will reside in the shared environment, and may be used by other transactions.

In contrast to LMDB, the MDBX allow this function to be called from multiple concurrent transactions or threads in the same process.

To use named table (with name != NULL), mdbx_env_set_maxdbs() must be called before opening the environment. Table names are keys in the internal unnamed table, and may be read but not written.

Parameters

[in]	txn	transaction handle returned by mdbx_txn_begin().
[in]	name	The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
[in]	flags	Special options for this table. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_DB_DEFAULTS Keys are arbitrary byte strings and compared from beginning to end.
• MDBX_REVERSEKEY Keys are arbitrary byte strings to be compared in reverse order, from the end of the strings to the beginning.
• MDBX_INTEGERKEY Keys are binary integers in native byte order, either uint32_t or uint64_t, and will be sorted as such. The keys must all be of the same size and must be aligned while passing as arguments.
• MDBX_DUPSORT Duplicate keys may be used in the table. Or, from another point of view, keys may have multiple data items, stored in sorted order. By default keys must be unique and may have only a single data item.
• MDBX_DUPFIXED This flag may only be used in combination with MDBX_DUPSORT. This option tells the library that the data items for this table are all the same size, which allows further optimizations in storage and retrieval. When all data items are the same size, the MDBX_GET_MULTIPLE, MDBX_NEXT_MULTIPLE and MDBX_PREV_MULTIPLE cursor operations may be used to retrieve multiple items at once.
• MDBX_INTEGERDUP This option specifies that duplicate data items are binary integers, similar to MDBX_INTEGERKEY keys. The data values must all be of the same size and must be aligned while passing as arguments.
• MDBX_REVERSEDUP This option specifies that duplicate data items should be compared as strings in reverse order (the comparison is performed in the direction from the last byte to the first).
• MDBX_CREATE Create the named table if it doesn't exist. This option is not allowed in a read-only transaction or a read-only environment.

Parameters

[out]

dbi

Address where the new MDBX_dbi handle will be stored.

For mdbx_dbi_open_ex() additional arguments allow you to set custom comparison functions for keys and values (for multimaps).

See also

avoid_custom_comparators

Returns

A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_NOTFOUND	The specified table doesn't exist in the environment and MDBX_CREATE was not specified.
MDBX_DBS_FULL	Too many tables have been opened.

See also

mdbx_env_set_maxdbs()

Return values

MDBX_INCOMPATIBLE	Table is incompatible with given flags, i.e. the passed flags is different with which the table was created, or the table was already opened with a different comparison function(s).
MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.

mdbx_dbi_open2()

LIBMDBX_API int mdbx_dbi_open2	(	MDBX_txn *	txn,
		const MDBX_val *	name,
		MDBX_db_flags_t	flags,
		MDBX_dbi *	dbi
	)

Open or Create a named table in the environment.

A table handle denotes the name and parameters of a table, independently of whether such a table exists. The table handle may be discarded by calling mdbx_dbi_close(). The old table handle is returned if the table was already open. The handle may only be closed once.

Note

A notable difference between MDBX and LMDB is that MDBX make handles opened for existing tables immediately available for other transactions, regardless this transaction will be aborted or reset. The REASON for this is to avoiding the requirement for multiple opening a same handles in concurrent read transactions, and tracking of such open but hidden handles until the completion of read transactions which opened them.

Nevertheless, the handle for the NEWLY CREATED table will be invisible for other transactions until the this write transaction is successfully committed. If the write transaction is aborted the handle will be closed automatically. After a successful commit the such handle will reside in the shared environment, and may be used by other transactions.

In contrast to LMDB, the MDBX allow this function to be called from multiple concurrent transactions or threads in the same process.

To use named table (with name != NULL), mdbx_env_set_maxdbs() must be called before opening the environment. Table names are keys in the internal unnamed table, and may be read but not written.

Parameters

[in]	txn	transaction handle returned by mdbx_txn_begin().
[in]	name	The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
[in]	flags	Special options for this table. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_DB_DEFAULTS Keys are arbitrary byte strings and compared from beginning to end.
• MDBX_REVERSEKEY Keys are arbitrary byte strings to be compared in reverse order, from the end of the strings to the beginning.
• MDBX_INTEGERKEY Keys are binary integers in native byte order, either uint32_t or uint64_t, and will be sorted as such. The keys must all be of the same size and must be aligned while passing as arguments.
• MDBX_DUPSORT Duplicate keys may be used in the table. Or, from another point of view, keys may have multiple data items, stored in sorted order. By default keys must be unique and may have only a single data item.
• MDBX_DUPFIXED This flag may only be used in combination with MDBX_DUPSORT. This option tells the library that the data items for this table are all the same size, which allows further optimizations in storage and retrieval. When all data items are the same size, the MDBX_GET_MULTIPLE, MDBX_NEXT_MULTIPLE and MDBX_PREV_MULTIPLE cursor operations may be used to retrieve multiple items at once.
• MDBX_INTEGERDUP This option specifies that duplicate data items are binary integers, similar to MDBX_INTEGERKEY keys. The data values must all be of the same size and must be aligned while passing as arguments.
• MDBX_REVERSEDUP This option specifies that duplicate data items should be compared as strings in reverse order (the comparison is performed in the direction from the last byte to the first).
• MDBX_CREATE Create the named table if it doesn't exist. This option is not allowed in a read-only transaction or a read-only environment.

Parameters

[out]

dbi

Address where the new MDBX_dbi handle will be stored.

For mdbx_dbi_open_ex() additional arguments allow you to set custom comparison functions for keys and values (for multimaps).

See also

avoid_custom_comparators

Returns

A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_NOTFOUND	The specified table doesn't exist in the environment and MDBX_CREATE was not specified.
MDBX_DBS_FULL	Too many tables have been opened.

See also

mdbx_env_set_maxdbs()

Return values

MDBX_INCOMPATIBLE	Table is incompatible with given flags, i.e. the passed flags is different with which the table was created, or the table was already opened with a different comparison function(s).
MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.

mdbx_dbi_open_ex()

LIBMDBX_API int mdbx_dbi_open_ex	(	MDBX_txn *	txn,
		const char *	name,
		MDBX_db_flags_t	flags,
		MDBX_dbi *	dbi,
		MDBX_cmp_func *	keycmp,
		MDBX_cmp_func *	datacmp
	)

Open or Create a named table in the environment with using custom comparison functions.

Deprecated:

Please avoid using custom comparators and use mdbx_dbi_open() instead.

Parameters

[in]	txn	transaction handle returned by mdbx_txn_begin().
[in]	name	The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
[in]	flags	Special options for this table.
[in]	keycmp	Optional custom key comparison function for a table.
[in]	datacmp	Optional custom data comparison function for a table.
[out]	dbi	Address where the new MDBX_dbi handle will be stored.

Returns

A non-zero error value on failure and 0 on success.

mdbx_dbi_open_ex2()

LIBMDBX_API int mdbx_dbi_open_ex2	(	MDBX_txn *	txn,
		const MDBX_val *	name,
		MDBX_db_flags_t	flags,
		MDBX_dbi *	dbi,
		MDBX_cmp_func *	keycmp,
		MDBX_cmp_func *	datacmp
	)

Open or Create a named table in the environment with using custom comparison functions.

Deprecated:

Please avoid using custom comparators and use mdbx_dbi_open() instead.

Parameters

[in]	txn	transaction handle returned by mdbx_txn_begin().
[in]	name	The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
[in]	flags	Special options for this table.
[in]	keycmp	Optional custom key comparison function for a table.
[in]	datacmp	Optional custom data comparison function for a table.
[out]	dbi	Address where the new MDBX_dbi handle will be stored.

Returns

A non-zero error value on failure and 0 on success.

mdbx_dbi_rename()

LIBMDBX_API int mdbx_dbi_rename	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const char *	name
	)

Переименовает таблицу по DBI-дескриптору

Переименовывает пользовательскую именованную таблицу связанную с передаваемым DBI-дескриптором.

Parameters

[in,out]	txn	Пишущая транзакция запущенная посредством mdbx_txn_begin().
[in]	dbi	Дескриптор таблицы открытый посредством mdbx_dbi_open().
[in]	name	Новое имя для переименования.

Returns

Ненулевое значение кода ошибки, либо 0 при успешном выполнении.

mdbx_dbi_rename2()

LIBMDBX_API int mdbx_dbi_rename2	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	name
	)

Переименовает таблицу по DBI-дескриптору

Переименовывает пользовательскую именованную таблицу связанную с передаваемым DBI-дескриптором.

Parameters

[in,out]	txn	Пишущая транзакция запущенная посредством mdbx_txn_begin().
[in]	dbi	Дескриптор таблицы открытый посредством mdbx_dbi_open().
[in]	name	Новое имя для переименования.

Returns

Ненулевое значение кода ошибки, либо 0 при успешном выполнении.