libmdbx  0.11.9.0 (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
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

◆ 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

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]envAn environment handle returned by mdbx_env_create().
[in]dbiA 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]txntransaction handle returned by mdbx_txn_begin().
[in]nameThe name of the database to open. If only a single database is needed in the environment, this value may be NULL.
[in]flagsSpecial 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]dbiAddress 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_NOTFOUNDThe specified database doesn't exist in the environment and MDBX_CREATE was not specified.
MDBX_DBS_FULLToo many databases have been opened.
See also
mdbx_env_set_maxdbs()
Return values
MDBX_INCOMPATIBLEDatabase 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_MISMATCHGiven 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]txntransaction handle returned by mdbx_txn_begin().
[in]nameThe name of the database to open. If only a single database is needed in the environment, this value may be NULL.
[in]flagsSpecial options for this database.
[in]keycmpOptional custom key comparison function for a database.
[in]datacmpOptional custom data comparison function for a database.
[out]dbiAddress where the new MDBX_dbi handle will be stored.
Returns
A non-zero error value on failure and 0 on success.