C API

Topics
	Error handling
	Opening & Closing
	Transactions
	Tables
	Create/Read/Update/Delete (see Quick Reference in details)
	Cursors
	Statistics & Information
	Settings
	Logging and runtime debug
	Range query estimation
	Extra operations
	Value-to-Key functions
	Value-to-Key functions to avoid using custom comparators.
	Key-to-Value functions
	Key-to-Value functions to avoid using custom comparators.
	Checking and Recovery

Classes
struct	MDBX_version_info
	libmdbx version information, More...
struct	MDBX_build_info
	libmdbx build information More...
struct	MDBX_stat
	Statistics for a table in the environment. More...
struct	MDBX_envinfo
	Information about the environment. More...
struct	MDBX_txn_info
	Information about the transaction. More...
struct	MDBX_commit_latency
	Latency of commit stages in 1/65536 of seconds units. More...
struct	MDBX_canary
	The fours integers markers (aka "canary") associated with the environment. More...
struct	MDBX_cache_entry_t
	Lightweight transparent cache entry structure used by mdbx_cache_get(). More...
struct	MDBX_cache_result_t
	Pair of error code and cache status as a result of mdbx_cache_get(). More...
struct	MDBX_gc_info_t
	Information about Garbage Collection and page usage. More...
struct	MDBX_defrag_result_t
	The numerical metrics of progress and result of database defragmentation. More...
struct	MDBX_version_info.git
struct	MDBX_envinfo.mi_geo
struct	MDBX_envinfo.mi_bootid
	A mostly unique ID that is regenerated on each boot. More...
struct	MDBX_envinfo.mi_bootid.current
struct	MDBX_envinfo.mi_bootid.meta
struct	MDBX_envinfo.mi_pgop_stat
struct	MDBX_envinfo.mi_dxbid
struct	MDBX_commit_latency.gc_prof
	Information for GC profiling. More...
struct	MDBX_commit_latency.gc_prof.pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages. More...
struct	MDBX_commit_latency.gc_prof.pnl_merge_self
	Metrics of the amount of work and cost of merging lists of pages. More...
struct	MDBX_gc_info_t.gc_reclaimable

Macros
#define	MDBX_AMALGAMATED_SOURCE   1
#define	MDBX_VERSION_UNSTABLE
#define	MDBX_VERSION_MAJOR   0
#define	MDBX_VERSION_MINOR   14
#define	LIBMDBX_API   __dll_export
#define	LIBMDBX_API_TYPE
#define	LIBMDBX_VERINFO_API   __dll_export
#define	MDBX_LOCKNAME   "/mdbx.lck"
	The name of the lock file in the environment without using MDBX_NOSUBDIR.
#define	MDBX_DATANAME   "/mdbx.dat"
	The name of the data file in the environment without using MDBX_NOSUBDIR.
#define	MDBX_LOCK_SUFFIX   "-lck"
	The suffix of the lock file when MDBX_NOSUBDIR is used.
#define	MDBX_MAP_RESIZED   MDBX_MAP_RESIZED_is_deprecated()
#define	mdbx_env_openT(env, pathname, flags, mode)
#define	mdbx_env_deleteT(pathname, mode)
#define	mdbx_env_copyT(env, dest, flags)
#define	mdbx_txn_copy2pathnameT(txn, dest, flags)
#define	mdbx_env_get_pathT(env, dest)

Typedefs
typedef int	mdbx_filehandle_t
typedef pid_t	mdbx_pid_t
typedef pthread_t	mdbx_tid_t
typedef mode_t	mdbx_mode_t
typedef struct MDBX_env	MDBX_env
	Opaque structure for a database environment.
typedef struct iovec	MDBX_val
	Generic structure used for passing keys and data in and out of the table. .

Enumerations
enum	MDBX_constants { MDBX_MAX_DBI = UINT32_C(32765) , MDBX_MAXDATASIZE = UINT32_C(0x7fff0000) , MDBX_MIN_PAGESIZE = 256 , MDBX_MAX_PAGESIZE = 65536 }

Functions
LIBMDBX_API const char *	mdbx_liberr2str (int errnum)
LIBMDBX_API int	mdbx_env_openW (MDBX_env *env, const wchar_t *pathname, MDBX_env_flags_t flags, mdbx_mode_t mode)
	Open an environment instance.
LIBMDBX_API MDBX_hsr_func	mdbx_env_get_hsr (const MDBX_env *env)
	Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

Variables
LIBMDBX_VERINFO_API const struct MDBX_version_info	mdbx_version
	libmdbx version information
LIBMDBX_VERINFO_API const struct MDBX_build_info	mdbx_build
	libmdbx build information

Detailed Description

---

Class Documentation

MDBX_version_info

struct MDBX_version_info

libmdbx version information,

See also

https://semver.org/

Public Attributes
uint16_t	major
uint16_t	minor
uint16_t	patch
uint16_t	tweak
const char *	semver_prerelease
struct {
const char *	datetime
const char *	tree
const char *	commit
const char *	describe
}	git
const char *	sourcery

Member Data Documentation

[struct]

struct { ... } MDBX_version_info::git

source information from git

major

uint16_t MDBX_version_info::major

Major version number

minor

uint16_t MDBX_version_info::minor

Minor version number

patch

uint16_t MDBX_version_info::patch

Patch number

semver_prerelease

const char* MDBX_version_info::semver_prerelease

Semantic Versioning pre-release

sourcery

const char* MDBX_version_info::sourcery

sourcery anchor for pinning

tweak

uint16_t MDBX_version_info::tweak

Tweak number

MDBX_build_info

struct MDBX_build_info

libmdbx build information

Attention

Some strings could be NULL in case no corresponding information was provided at build time (i.e. flags).

Class Members
const char *	compiler	compiler
const char *	datetime	build timestamp (ISO-8601 or DATE TIME)
const char *	flags	CFLAGS and CXXFLAGS
const char *	metadata	an extra/custom information provided via the MDBX_BUILD_METADATA definition during library build
const char *	options	mdbx-related options
const char *	target	cpu/arch-system-config triplet

MDBX_stat

struct MDBX_stat

Statistics for a table in the environment.

See also

mdbx_env_stat_ex()

mdbx_dbi_stat()

Class Members
uint64_t	ms_branch_pages	Number of internal (non-leaf) pages
uint32_t	ms_depth	Depth (height) of the B-tree
uint64_t	ms_entries	Number of data items
uint64_t	ms_leaf_pages	Number of leaf pages
uint64_t	ms_mod_txnid	Transaction ID of committed last modification
uint64_t	ms_overflow_pages	Number of large/overflow pages
uint32_t	ms_psize	Size of a table page. This is the same for all tables in a database.

MDBX_envinfo

struct MDBX_envinfo

Information about the environment.

See also

mdbx_env_info_ex()

Public Attributes
struct {
uint64_t	lower
uint64_t	upper
uint64_t	current
uint64_t	shrink
uint64_t	grow
}	mi_geo
uint64_t	mi_mapsize
uint64_t	mi_dxb_fsize
uint64_t	mi_dxb_fallocated
uint64_t	mi_last_pgno
uint64_t	mi_recent_txnid
uint64_t	mi_latter_reader_txnid
uint64_t	mi_self_latter_reader_txnid
uint64_t	mi_meta_txnid [3]
uint64_t	mi_meta_sign [3]
uint32_t	mi_maxreaders
uint32_t	mi_numreaders
uint32_t	mi_dxb_pagesize
uint32_t	mi_sys_pagesize
uint32_t	mi_sys_upcblk
uint32_t	mi_sys_ioblk
struct {
struct {
uint64_t	x
uint64_t	y
}	current
struct {
uint64_t	x
uint64_t	y
}	meta [3]
}	mi_bootid
	A mostly unique ID that is regenerated on each boot.
uint64_t	mi_unsync_volume
uint64_t	mi_autosync_threshold
uint32_t	mi_since_sync_seconds16dot16
uint32_t	mi_autosync_period_seconds16dot16
uint32_t	mi_since_reader_check_seconds16dot16
uint32_t	mi_mode
struct {
uint64_t	newly
uint64_t	cow
uint64_t	clone
uint64_t	split
uint64_t	merge
uint64_t	spill
uint64_t	unspill
uint64_t	wops
uint64_t	prefault
uint64_t	mincore
uint64_t	msync
uint64_t	fsync
}	mi_pgop_stat
struct {
uint64_t	x
uint64_t	y
}	mi_dxbid

Member Data Documentation

mi_autosync_period_seconds16dot16

uint32_t MDBX_envinfo::mi_autosync_period_seconds16dot16

Current auto-sync period in 1/65536 of second, see mdbx_env_set_syncperiod().

mi_autosync_threshold

uint64_t MDBX_envinfo::mi_autosync_threshold

Current auto-sync threshold, see mdbx_env_set_syncbytes().

[struct]

struct { ... } MDBX_envinfo::mi_bootid

A mostly unique ID that is regenerated on each boot.

As such it can be used to identify the local machine's current boot. MDBX uses such when open the database to determine whether rollback required to the last steady sync point or not. I.e. if current bootid is differ from the value within a database then the system was rebooted and all changes since last steady sync must be reverted for data integrity. Zeros mean that no relevant information is available from the system.

mi_dxb_fallocated

uint64_t MDBX_envinfo::mi_dxb_fallocated

Space allocated for the database file in a filesystem

mi_dxb_fsize

uint64_t MDBX_envinfo::mi_dxb_fsize

Current database file size

mi_dxb_pagesize

uint32_t MDBX_envinfo::mi_dxb_pagesize

Database pagesize

[struct]

struct { ... } MDBX_envinfo::mi_dxbid

[struct]

struct { ... } MDBX_envinfo::mi_geo

mi_last_pgno

uint64_t MDBX_envinfo::mi_last_pgno

Number of the last used page

mi_latter_reader_txnid

uint64_t MDBX_envinfo::mi_latter_reader_txnid

ID of the last reader transaction

mi_mapsize

uint64_t MDBX_envinfo::mi_mapsize

Size of the database memory map

mi_maxreaders

uint32_t MDBX_envinfo::mi_maxreaders

Total reader slots in the environment

mi_meta_sign

uint64_t MDBX_envinfo::mi_meta_sign[3]

mi_meta_txnid

uint64_t MDBX_envinfo::mi_meta_txnid[3]

mi_mode

uint32_t MDBX_envinfo::mi_mode

Current environment mode. The same as mdbx_env_get_flags() returns.

mi_numreaders

uint32_t MDBX_envinfo::mi_numreaders

Max reader slots used in the environment

[struct]

struct { ... } MDBX_envinfo::mi_pgop_stat

Statistics of page operations.

Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).

mi_recent_txnid

uint64_t MDBX_envinfo::mi_recent_txnid

ID of the last committed transaction

mi_self_latter_reader_txnid

uint64_t MDBX_envinfo::mi_self_latter_reader_txnid

ID of the last reader transaction of this/current process

mi_since_reader_check_seconds16dot16

uint32_t MDBX_envinfo::mi_since_reader_check_seconds16dot16

Time since the last readers check in 1/65536 of second, see mdbx_reader_check().

mi_since_sync_seconds16dot16

uint32_t MDBX_envinfo::mi_since_sync_seconds16dot16

Time since entering to a "dirty" out-of-sync state in units of 1/65536 of second. In other words, this is the time since the last non-steady commit or zero if it was steady.

mi_sys_ioblk

uint32_t MDBX_envinfo::mi_sys_ioblk

Filesystem I/O block size

mi_sys_pagesize

uint32_t MDBX_envinfo::mi_sys_pagesize

System pagesize

mi_sys_upcblk

uint32_t MDBX_envinfo::mi_sys_upcblk

System "Unified Page Cache" block size

mi_unsync_volume

uint64_t MDBX_envinfo::mi_unsync_volume

Bytes not explicitly synchronized to disk

MDBX_txn_info

struct MDBX_txn_info

Information about the transaction.

See also

mdbx_txn_info

Class Members
uint64_t	txn_id	The ID of the transaction. For a READ-ONLY transaction, this corresponds to the snapshot being read.
uint64_t	txn_pget	Number of page get operations within this transaction if corresponding statistics enabled via MDBX_ENABLE_PGET_STAT build option.
uint64_t	txn_reader_lag	For READ-ONLY transaction: the lag from a recent MVCC-snapshot, i.e. the number of committed transaction since read transaction started. For WRITE transaction (provided if scan_rlt=true): the lag of the oldest reader from current transaction (i.e. at least 1 if any reader running).
uint64_t	txn_space_dirty	For READ-ONLY transaction (provided if scan_rlt=true): The space that actually become available for reuse when only this transaction will be finished. For WRITE transaction: The summarized size of the dirty database pages that generated during this transaction.
uint64_t	txn_space_leftover	For READ-ONLY transaction: the space available for writer(s) and that must be exhausted for reason to call the Handle-Slow-Readers callback for this read transaction. For WRITE transaction: the space inside transaction that left to MDBX_TXN_FULL error.
uint64_t	txn_space_limit_hard	Upper bound for size the database file, i.e. the value size_upper argument of the appropriate call of mdbx_env_set_geometry().
uint64_t	txn_space_limit_soft	Current size of database file.
uint64_t	txn_space_retired	For READ-ONLY transaction: The total size of the database pages that were retired by committed write transactions after the reader's MVCC-snapshot, i.e. the space which would be freed after the Reader releases the MVCC-snapshot for reuse by completion read transaction. For WRITE transaction: The summarized size of the database pages that were retired for now due Copy-On-Write during this transaction.
uint64_t	txn_space_used	Used space by this transaction, i.e. corresponding to the last used database page.

MDBX_commit_latency

struct MDBX_commit_latency

Latency of commit stages in 1/65536 of seconds units.

Warning

This structure may be changed in future releases.

See also

mdbx_txn_commit_ex()

Public Attributes
uint32_t	preparation
	Duration of preparation (commit child transactions, update table's records and cursors destroying).
uint32_t	gc_wallclock
	Duration of GC update by wall clock.
uint32_t	audit
	Duration of internal audit if enabled.
uint32_t	write
	Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a write() syscalls during commit.
uint32_t	sync
	Duration of syncing written data to the disk/storage, i.e. the duration of a fdatasync() or a msync() syscall during commit.
uint32_t	ending
	Duration of transaction ending (releasing resources).
uint32_t	whole
	The total duration of a commit.
uint32_t	gc_cputime
	User-mode CPU time spent on GC update.
struct {
uint32_t	wloops
	The number of GC update iterations is greater than 1 if there were repeats/restarts.
uint32_t	coalescences
	The number of iterations of merging GC items.
uint32_t	wipes
	The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.
uint32_t	flushes
	The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.
uint32_t	kicks
	The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.
uint32_t	work_counter
	Number of slow/deep path GC search for the sake of placement user's data.
uint32_t	work_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the user's data.
uint32_t	work_xtime_cpu
	The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.
uint32_t	work_rsteps
	The number of search iterations inside GC when allocating pages for the sake of user's data.
uint32_t	work_xpages
	The number of requests to allocate page sequences for the sake of user's data.
uint32_t	work_majflt
	The number of page faults inside the GC when allocating and preparing pages for user's data.
uint32_t	self_counter
	The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.
uint32_t	self_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.
uint32_t	self_xtime_cpu
	The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.
uint32_t	self_rsteps
	The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.
uint32_t	self_xpages
	The number of page sequences allocation requests for the GC itself.
uint32_t	self_majflt
	The number of page faults within the GC when allocating and preparing pages for the GC itself.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_self
uint32_t	max_reader_lag
	The maximum observed difference between the latest and oldest readed MVCC-snapshots.
uint32_t	max_retained_pages
	The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.
}	gc_prof
	Information for GC profiling.

Member Data Documentation

audit

uint32_t MDBX_commit_latency::audit

Duration of internal audit if enabled.

ending

uint32_t MDBX_commit_latency::ending

Duration of transaction ending (releasing resources).

gc_cputime

uint32_t MDBX_commit_latency::gc_cputime

User-mode CPU time spent on GC update.

[struct]

struct { ... } MDBX_commit_latency::gc_prof

Information for GC profiling.

Note

This data is shared for all processes working with a given database and stored in LCK-file.

Statistic is accumulated when all transactions are committed, but only in libmdbx builds with the MDBX_ENABLE_PROFGC option enabled. The collected statistics are returned to any process when using mdbx_txn_commit_ex() or mdbx_txn_checkpoint(), and at the same time they are reset to zero when top-level transactions (not nested) are committed.

gc_wallclock

uint32_t MDBX_commit_latency::gc_wallclock

Duration of GC update by wall clock.

preparation

uint32_t MDBX_commit_latency::preparation

Duration of preparation (commit child transactions, update table's records and cursors destroying).

sync

uint32_t MDBX_commit_latency::sync

Duration of syncing written data to the disk/storage, i.e. the duration of a fdatasync() or a msync() syscall during commit.

whole

uint32_t MDBX_commit_latency::whole

The total duration of a commit.

write

uint32_t MDBX_commit_latency::write

Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a write() syscalls during commit.

MDBX_canary

struct MDBX_canary

The fours integers markers (aka "canary") associated with the environment.

See also

mdbx_canary_put()

mdbx_canary_get()

The x, y and z values could be set by mdbx_canary_put(), while the v will be always set to the transaction number. Updated values becomes visible outside the current transaction only after it was committed. Current values could be retrieved by mdbx_canary_get().

Class Members
uint64_t	v
uint64_t	x
uint64_t	y
uint64_t	z

MDBX_cache_entry_t

struct MDBX_cache_entry_t

Lightweight transparent cache entry structure used by mdbx_cache_get().

The approach of these caching is to preserve address of a value retrieved from the database with an extremely fast check of relevance it based on a transaction ID within an internal b-tree structures. Event a b-tree was modified then the search for the corresponding key from the root of the b-tree to leaf pages stops as soon as reaches a page that has not been modified after the last check of given cache entry. This way, the minimum actions is performed, which is no slower than a usual key search in the worst case, and at best, only a few lightweight checks will be do.

Note

The cache structure allows it to be placed in shared memory and used by multiple processes. However, such interaction and management are not provided by libmdbx in any way yet now.

An each cache entry must be initialized by mdbx_cache_init() before first use.

Inherited by mdbx::cache_entry.

Public Attributes
uint64_t	trunk_txnid
uint64_t	last_confirmed_txnid
size_t	offset
uint32_t	length

Member Data Documentation

last_confirmed_txnid

uint64_t MDBX_cache_entry_t::last_confirmed_txnid

The recent transaction/MVCC-snapshot ID wherein the cache entry was checked and confirmed.

length

uint32_t MDBX_cache_entry_t::length

The length of cached data value for a corresponding key.

offset

size_t MDBX_cache_entry_t::offset

The offset of cached data value for a corresponding key. The zero value means MDBX_NOTFOUND.

trunk_txnid

uint64_t MDBX_cache_entry_t::trunk_txnid

The transaction/MVCC-snapshot ID of a page or other internal DB structure that hold the cached data or reflect it state.

MDBX_cache_result_t

struct MDBX_cache_result_t

Pair of error code and cache status as a result of mdbx_cache_get().

See also

mdbx_cache_get()

mdbx_cache_get_SingleThreaded()

Class Members
MDBX_error_t	errcode	The error code of getting data same as from mdbx_get().
MDBX_cache_status_t	status	The result of cache operation as the value of MDBX_cache_status_t.

MDBX_gc_info_t

struct MDBX_gc_info_t

Information about Garbage Collection and page usage.

See also

mdbx_gc_info

Public Attributes
size_t	pages_total
size_t	pages_backed
size_t	pages_allocated
size_t	pages_gc
struct {
size_t	pages
struct MDBX_chk_histogram	span_histogram
struct MDBX_chk_histogram	pgno_distribution
}	gc_reclaimable
size_t	max_reader_lag
size_t	max_retained_pages

Member Data Documentation

[struct]

struct { ... } MDBX_gc_info_t::gc_reclaimable

max_reader_lag

size_t MDBX_gc_info_t::max_reader_lag

max_retained_pages

size_t MDBX_gc_info_t::max_retained_pages

pages_allocated

size_t MDBX_gc_info_t::pages_allocated

Number of pages currently allocated

pages_backed

size_t MDBX_gc_info_t::pages_backed

Number of pages currently backed by a database file

pages_gc

size_t MDBX_gc_info_t::pages_gc

Number of all pages within GC, includes a pages formes the B-tree structure of GC itself

pages_total

size_t MDBX_gc_info_t::pages_total

Total number of pages in a database, i.e. the upper limit defined by geometry

MDBX_defrag_result_t

struct MDBX_defrag_result_t

The numerical metrics of progress and result of database defragmentation.

See also

mdbx_env_defrag()

MDBX_defrag_notify_func

Class Members
unsigned	cycles	The number of defragmentation cycles.
size_t	obstructed_pgno	The number of the page where the defragmentation stumbled, according to the reasons given in the stopping_reasons field.
size_t	obstructed_span	The length of the large/overflow-page span where the defragmentation stumbled, according to the reasons given in the stopping_reasons field.
uint64_t	obstructed_txnid	The transaction number corresponds to the earliest/first MVCC-snapshot held by reader(s) and preventing defragmentation.
mdbx_pid_t	obstructor_pid	The system/native Process ID of one of a readers holding the MVCC snapshot that prevents defragmentation.
mdbx_tid_t	obstructor_tid	The system/native Thread ID of one of a readers holding the MVCC snapshot that prevents defragmentation.
size_t	pages_left	The estimated remaining number of pages that are potentially defragmented.
size_t	pages_moved	The total number of pages moved during defragmentation.
size_t	pages_retained	The number of pages held by other processes via reading MVCC-snapshots that prevent reclaiming and defragmentation.
size_t	pages_scheduled	The number of pages scheduled to be moved at the next stage of the current defragmentation cycle.
intptr_t	pages_shrinked	The number of pages that the database size was shrinked by. In the worst case, this value can be negative, for instance -1, when defragmentation was stopped for some reason, or the database structure does not allow it to be defragmented by moving individual pages.
size_t	pages_whole	The whole number of pages in the database.
unsigned	rough_estimation_cycle_progress_permille	Rough estimation a progress of the current defragmentation cycle in permilles (the 1000 means 100%).
size_t	spent_time_dot16	The time elapsed since the beginning of defragmentation in a 1/65536 second fractions.
unsigned	stopping_reasons	Obstacles and reasons for stopping defragmentation in the form of a mask of OR'ed MDBX_defrag_stopping_reasons_t bits.

MDBX_version_info.git

struct MDBX_version_info.git

Class Members
const char *	commit	tree hash, i.e. digest of the source code
const char *	datetime	committer date, strict ISO-8601 format
const char *	describe	git-describe string
const char *	tree	commit hash (hexadecimal digits)

MDBX_envinfo.mi_geo

struct MDBX_envinfo.mi_geo

Class Members
uint64_t	current	Current datafile size
uint64_t	grow	Growth step for datafile
uint64_t	lower	Lower limit for datafile size
uint64_t	shrink	Shrink threshold for datafile
uint64_t	upper	Upper limit for datafile size

MDBX_envinfo.mi_bootid

struct MDBX_envinfo.mi_bootid

A mostly unique ID that is regenerated on each boot.

As such it can be used to identify the local machine's current boot. MDBX uses such when open the database to determine whether rollback required to the last steady sync point or not. I.e. if current bootid is differ from the value within a database then the system was rebooted and all changes since last steady sync must be reverted for data integrity. Zeros mean that no relevant information is available from the system.

Public Attributes
struct {
uint64_t	x
uint64_t	y
}	current
struct {
uint64_t	x
uint64_t	y
}	meta [3]

Member Data Documentation

current

meta

MDBX_envinfo.mi_bootid.current

struct MDBX_envinfo.mi_bootid.current

Class Members
uint64_t	x
uint64_t	y

MDBX_envinfo.mi_bootid.meta

struct MDBX_envinfo.mi_bootid.meta

Class Members
uint64_t	x
uint64_t	y

MDBX_envinfo.mi_pgop_stat

struct MDBX_envinfo.mi_pgop_stat

Statistics of page operations.

Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).

Class Members
uint64_t	clone	Quantity of parent's dirty pages clones for nested transactions
uint64_t	cow	Quantity of pages copied for update
uint64_t	fsync	Number of explicit fsync-to-disk operations (not a pages)
uint64_t	merge	Page merges
uint64_t	mincore	Number of mincore() calls
uint64_t	msync	Number of explicit msync-to-disk operations (not a pages)
uint64_t	newly	Quantity of a new pages added
uint64_t	prefault	Number of prefault write operations (not a pages)
uint64_t	spill	Quantity of spilled dirty pages
uint64_t	split	Page splits
uint64_t	unspill	Quantity of unspilled/reloaded pages
uint64_t	wops	Number of explicit write operations (not a pages) to a disk

MDBX_envinfo.mi_dxbid

struct MDBX_envinfo.mi_dxbid

Class Members
uint64_t	x
uint64_t	y

MDBX_commit_latency.gc_prof

struct MDBX_commit_latency.gc_prof

Information for GC profiling.

Note

This data is shared for all processes working with a given database and stored in LCK-file.

Statistic is accumulated when all transactions are committed, but only in libmdbx builds with the MDBX_ENABLE_PROFGC option enabled. The collected statistics are returned to any process when using mdbx_txn_commit_ex() or mdbx_txn_checkpoint(), and at the same time they are reset to zero when top-level transactions (not nested) are committed.

Public Attributes
uint32_t	wloops
	The number of GC update iterations is greater than 1 if there were repeats/restarts.
uint32_t	coalescences
	The number of iterations of merging GC items.
uint32_t	wipes
	The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.
uint32_t	flushes
	The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.
uint32_t	kicks
	The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.
uint32_t	work_counter
	Number of slow/deep path GC search for the sake of placement user's data.
uint32_t	work_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the user's data.
uint32_t	work_xtime_cpu
	The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.
uint32_t	work_rsteps
	The number of search iterations inside GC when allocating pages for the sake of user's data.
uint32_t	work_xpages
	The number of requests to allocate page sequences for the sake of user's data.
uint32_t	work_majflt
	The number of page faults inside the GC when allocating and preparing pages for user's data.
uint32_t	self_counter
	The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.
uint32_t	self_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.
uint32_t	self_xtime_cpu
	The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.
uint32_t	self_rsteps
	The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.
uint32_t	self_xpages
	The number of page sequences allocation requests for the GC itself.
uint32_t	self_majflt
	The number of page faults within the GC when allocating and preparing pages for the GC itself.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_self
uint32_t	max_reader_lag
	The maximum observed difference between the latest and oldest readed MVCC-snapshots.
uint32_t	max_retained_pages
	The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.

Member Data Documentation

coalescences

The number of iterations of merging GC items.

flushes

The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.

kicks

The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.

See also

MDBX_hsr_func

max_reader_lag

The maximum observed difference between the latest and oldest readed MVCC-snapshots.

max_retained_pages

The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.

pnl_merge_self

pnl_merge_work

Metrics of the amount of work and cost of merging lists of pages.

self_counter

The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.

self_majflt

The number of page faults within the GC when allocating and preparing pages for the GC itself.

self_rsteps

The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.

self_rtime_monotonic

The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.

self_xpages

The number of page sequences allocation requests for the GC itself.

self_xtime_cpu

The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.

wipes

The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.

wloops

The number of GC update iterations is greater than 1 if there were repeats/restarts.

work_counter

Number of slow/deep path GC search for the sake of placement user's data.

work_majflt

The number of page faults inside the GC when allocating and preparing pages for user's data.

work_rsteps

The number of search iterations inside GC when allocating pages for the sake of user's data.

work_rtime_monotonic

The time "by the wall clock" spent reading and searching inside the GC for the user's data.

work_xpages

The number of requests to allocate page sequences for the sake of user's data.

work_xtime_cpu

The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.

MDBX_commit_latency.gc_prof.pnl_merge_work

struct MDBX_commit_latency.gc_prof.pnl_merge_work

Metrics of the amount of work and cost of merging lists of pages.

Class Members
uint32_t	calls
uint32_t	time
uint64_t	volume

MDBX_commit_latency.gc_prof.pnl_merge_self

struct MDBX_commit_latency.gc_prof.pnl_merge_self

Metrics of the amount of work and cost of merging lists of pages.

Class Members
uint32_t	calls
uint32_t	time
uint64_t	volume

MDBX_gc_info_t.gc_reclaimable

struct MDBX_gc_info_t.gc_reclaimable

Class Members
size_t	pages	Number of reclaimable pages, including pending reserve within a current write transaction
struct MDBX_chk_histogram	pgno_distribution	Distribution of a reclaimable pages over the file of a database
struct MDBX_chk_histogram	span_histogram	Histogram of the spans length of a sequence(s) adjacent reclaimable pages

Macro Definition Documentation

LIBMDBX_API

#define LIBMDBX_API   __dll_export

LIBMDBX_API_TYPE

#define LIBMDBX_API_TYPE

LIBMDBX_VERINFO_API

#define LIBMDBX_VERINFO_API   __dll_export

MDBX_AMALGAMATED_SOURCE

#define MDBX_AMALGAMATED_SOURCE   1

MDBX_DATANAME

#define MDBX_DATANAME   "/mdbx.dat"

The name of the data file in the environment without using MDBX_NOSUBDIR.

mdbx_env_copyT

#define mdbx_env_copyT	(		env,
			dest,
			flags )

Value:

mdbx_env_copyW(env, dest, flags)

mdbx_env_deleteT

#define mdbx_env_deleteT	(		pathname,
			mode )

Value:

mdbx_env_deleteW(pathname, mode)

mdbx_env_get_pathT

#define mdbx_env_get_pathT	(		env,
			dest )

Value:

mdbx_env_get_pathW(env, dest)

mdbx_env_openT

#define mdbx_env_openT	(		env,
			pathname,
			flags,
			mode )

Value:

mdbx_env_openW(env, pathname, flags, mode)

MDBX_LOCK_SUFFIX

#define MDBX_LOCK_SUFFIX   "-lck"

The suffix of the lock file when MDBX_NOSUBDIR is used.

MDBX_LOCKNAME

#define MDBX_LOCKNAME   "/mdbx.lck"

The name of the lock file in the environment without using MDBX_NOSUBDIR.

MDBX_MAP_RESIZED

#define MDBX_MAP_RESIZED   MDBX_MAP_RESIZED_is_deprecated()

mdbx_txn_copy2pathnameT

#define mdbx_txn_copy2pathnameT	(		txn,
			dest,
			flags )

Value:

mdbx_txn_copy2pathnameW(txn, dest, path)

MDBX_VERSION_MAJOR

#define MDBX_VERSION_MAJOR   0

MDBX_VERSION_MINOR

#define MDBX_VERSION_MINOR   14

MDBX_VERSION_UNSTABLE

#define MDBX_VERSION_UNSTABLE

Typedef Documentation

MDBX_env

typedef struct MDBX_env MDBX_env

Opaque structure for a database environment.

An environment supports multiple key-value tables (aka key-value maps, spaces or sub-databases), all residing in the same shared-memory map.

See also

mdbx_env_create()

mdbx_env_close()

mdbx_filehandle_t

typedef int mdbx_filehandle_t

mdbx_mode_t

typedef mode_t mdbx_mode_t

mdbx_pid_t

typedef pid_t mdbx_pid_t

mdbx_tid_t

typedef pthread_t mdbx_tid_t

MDBX_val

typedef struct iovec MDBX_val

Generic structure used for passing keys and data in and out of the table. .

See also

mdbx::slice

mdbx::buffer

Values returned from the table are valid only until a subsequent update operation, or the end of the transaction. Do not modify or free them, they commonly point into the database itself.

Key sizes must be between 0 and mdbx_env_get_maxkeysize() inclusive. The same applies to data sizes in tables with the MDBX_DUPSORT flag. Other data items can in theory be from 0 to MDBX_MAXDATASIZE bytes long.

Note

The notable difference between MDBX and LMDB is that MDBX support zero length keys.

Enumeration Type Documentation

MDBX_constants

enum MDBX_constants

Enumerator
MDBX_MAX_DBI	The hard limit for DBI handles.
MDBX_MAXDATASIZE	The maximum size of a data item.
MDBX_MIN_PAGESIZE	The minimal database page size in bytes.
MDBX_MAX_PAGESIZE	The maximal database page size in bytes.

Function Documentation

mdbx_env_get_hsr()

LIBMDBX_API MDBX_hsr_func mdbx_env_get_hsr

(

const MDBX_env *

env

)

Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

See also

MDBX_hsr_func

mdbx_env_set_hsr()

mdbx_txn_park()

Long-lived read transactions

Parameters

[in]

env

An environment handle returned by mdbx_env_create().

Returns

A MDBX_hsr_func function or NULL if disabled or something wrong.

mdbx_env_openW()

LIBMDBX_API int mdbx_env_openW	(	MDBX_env *	env,
		const wchar_t *	pathname,
		MDBX_env_flags_t	flags,
		mdbx_mode_t	mode )

Open an environment instance.

Indifferently this function will fails or not, the mdbx_env_close() must be called later to discard the MDBX_env handle and release associated resources.

Note

On Windows the mdbx_env_openW() is recommended to use.

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[in]	pathname	The pathname for the database or the directory in which the database files reside. In the case of directory it must already exist and be writable.
[in]	flags	Specifies options for this environment. This parameter must be bitwise OR'ing together any constants described above in the env_flags and SYNC MODES sections.

Flags set by mdbx_env_set_flags() are also used:

• MDBX_ENV_DEFAULTS, MDBX_NOSUBDIR, MDBX_RDONLY, MDBX_EXCLUSIVE, MDBX_WRITEMAP, MDBX_NOSTICKYTHREADS, MDBX_NORDAHEAD, MDBX_NOMEMINIT, MDBX_COALESCE, MDBX_LIFORECLAIM. See env_flags section.
• MDBX_SYNC_DURABLE, MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC. See SYNC MODES section.

Note

MDB_NOLOCK flag don't supported by MDBX, try use MDBX_EXCLUSIVE as a replacement.

MDBX don't allow to mix processes with different MDBX_SAFE_NOSYNC flags on the same environment. In such case MDBX_INCOMPATIBLE will be returned.

If the database is already exist and parameters specified early by mdbx_env_set_geometry() are incompatible (i.e. for instance, different page size) then mdbx_env_open() will return MDBX_INCOMPATIBLE error.

Parameters

[in]

mode

The UNIX permissions to set on created files. Zero value means to open existing, but do not create.

Returns

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

Return values

MDBX_VERSION_MISMATCH	The version of the MDBX library doesn't match the version that created the database environment.
MDBX_INVALID	The environment file headers are corrupted.
MDBX_ENOENT	The directory specified by the path parameter doesn't exist.
MDBX_EACCES	The user didn't have permission to access the environment files.
MDBX_BUSY	The MDBX_EXCLUSIVE flag was specified and the environment is in use by another process, or the current process tries to open environment more than once.
MDBX_INCOMPATIBLE	Environment is already opened by another process, but with different set of MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC flags. Or if the database is already exist and parameters specified early by mdbx_env_set_geometry() are incompatible (i.e. different pagesize, etc).
MDBX_WANNA_RECOVERY	The MDBX_RDONLY flag was specified but read-write access is required to rollback inconsistent state after a system crash.
MDBX_TOO_LARGE	Database is too large for this process, i.e. 32-bit process tries to open >4Gb database.

Note

Available only on Windows.

See also

mdbx_env_open()

mdbx_liberr2str()

LIBMDBX_API const char * mdbx_liberr2str

(

int

errnum

)

Variable Documentation

mdbx_build

LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build

libmdbx build information

mdbx_version

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version

libmdbx version information