Databases

Typedefs
typedef uint32_t	MDBX_dbi
	A handle for an individual database (key-value spaces) in the environment. More...
typedef enum MDBX_db_flags_t	MDBX_db_flags_t

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 }
	Database 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 database in the environment. More...
MDBX_DEPRECATED 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)
LIBMDBX_API int	mdbx_dbi_close (MDBX_env *env, MDBX_dbi dbi)
	Close a database handle. Normally unnecessary. More...

Detailed Description

Typedef Documentation

MDBX_db_flags_t

typedef enum MDBX_db_flags_t MDBX_db_flags_t

MDBX_dbi

typedef uint32_t MDBX_dbi

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

Zero handle is used internally (hidden Garbage Collection subDB). 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

Database 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 sub-database created with unknown flags. The MDBX_DB_ACCEDE flag is intend to open a existing sub-database 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 sub-database 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 database handle. Normally unnecessary.

Closing a database 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_close(), but NOT with other transactions running by other threads. The "next" version of libmdbx (MithrilDB) will solve this issue.

Handles should only be closed if no other threads are going to reference the database handle or one of its cursors any further. Do not close a handle if an existing transaction has modified its database. Doing so can cause misbehavior from database 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 database 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 database in the environment.

A database handle denotes the name and parameters of a database, independently of whether such a database exists. The database handle may be discarded by calling mdbx_dbi_close(). The old database handle is returned if the database 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 databases 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 database 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 database (with name != NULL), mdbx_env_set_maxdbs() must be called before opening the environment. Table names are keys in the internal unnamed database, and may be read but not written.

Parameters

[in]	txn	transaction handle returned by mdbx_txn_begin().
[in]	name	The name of the database to open. If only a single database is needed in the environment, this value may be NULL.
[in]	flags	Special options for this database. 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 database. 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 database 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 database 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 database doesn't exist in the environment and MDBX_CREATE was not specified.
MDBX_DBS_FULL	Too many databases have been opened.

See also

mdbx_env_set_maxdbs()

Return values

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

mdbx_dbi_open_ex()

MDBX_DEPRECATED 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
	)

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 database to open. If only a single database is needed in the environment, this value may be NULL.
[in]	flags	Special options for this database.
[in]	keycmp	Optional custom key comparison function for a database.
[in]	datacmp	Optional custom data comparison function for a database.
[out]	dbi	Address where the new MDBX_dbi handle will be stored.

Returns

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