Group c_dbi

Public Types

Type	Name
enum	MDBX_db_flags_t Table flags .
typedef uint32_t	MDBX_dbi A handle for an individual table (key-value spaces) in the environment.

Public Functions

Type	Name
LIBMDBX_API int	mdbx_dbi_close (MDBX_env * env, MDBX_dbi dbi) Close a table handle. Normally unnecessary.
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) Renames the table using the DBI descriptor.
LIBMDBX_API int	mdbx_dbi_rename2 (MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * name) Renames the table using the DBI descriptor.

Public Types Documentation

enum MDBX_db_flags_t

Table flags .

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
};

See also: mdbx_dbi_open()

typedef MDBX_dbi

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

typedef uint32_t MDBX_dbi;

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

See also: mdbx_dbi_close()

Public Functions Documentation

function mdbx_dbi_close

Close a table handle. Normally unnecessary.

LIBMDBX_API int mdbx_dbi_close (
    MDBX_env * env,
    MDBX_dbi dbi
)

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 transaction(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:

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

Returns:

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

function mdbx_dbi_open

Open or Create a named table in the environment.

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

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:

txn transaction handle returned by mdbx_txn_begin().
name The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
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:

dbi Address where the new MDBX_dbi handle will be stored.

The name in mdbx_dbi_open() is a null terminated string. While mdbx_dbi_open2() supports arbitrary length keys which are not truncated, for example to support a fixed width integer type.

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 value:

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 value:

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.

function mdbx_dbi_open2

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
)

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:

txn transaction handle returned by mdbx_txn_begin().
name The name of the table to open. If only a single table is needed in the environment, this value may be NULL.
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:

dbi Address where the new MDBX_dbi handle will be stored.

The name in mdbx_dbi_open() is a null terminated string. While mdbx_dbi_open2() supports arbitrary length keys which are not truncated, for example to support a fixed width integer type.

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 value:

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 value:

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.

function mdbx_dbi_open_ex

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

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:

txn A transaction handle returned by mdbx_txn_begin().
name The name of the table to open. If only a single table is needed in the environment, this value may be NULL. The name in mdbx_dbi_open_ex() is null terminated, while mdbx_dbi_open_ex2() supports an arbitrary length.
flags Special options for this table.
keycmp Optional custom key comparison function for a table.
datacmp Optional custom data comparison function for a table.
dbi Address where the new MDBX_dbi handle will be stored.

Returns:

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

function mdbx_dbi_open_ex2

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
)

Deprecated

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

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
name The name of the table to open. If only a single table is needed in the environment, this value may be NULL. The name in mdbx_dbi_open_ex() is null terminated, while mdbx_dbi_open_ex2() supports an arbitrary length.
flags Special options for this table.
keycmp Optional custom key comparison function for a table.
datacmp Optional custom data comparison function for a table.
dbi Address where the new MDBX_dbi handle will be stored.

Returns:

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

function mdbx_dbi_rename

Renames the table using the DBI descriptor.

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

Renames the user's named table associated with the given DBI descriptor.

Parameters:

txn A writing transaction started by mdbx_txn_begin().
dbi The table descriptor is opened using mdbx_dbi_open().
name A new name to rename.

Returns:

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

function mdbx_dbi_rename2

Renames the table using the DBI descriptor.

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

Renames the user's named table associated with the given DBI descriptor.

Parameters:

txn A writing transaction started by mdbx_txn_begin().
dbi The table descriptor is opened using mdbx_dbi_open().
name A new name to rename.

Returns:

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