Extra operations

Modules
	Checking and Recovery

Enumerations
enum	MDBX_copy_flags_t {   MDBX_CP_DEFAULTS = 0 , MDBX_CP_COMPACT = 1u , MDBX_CP_FORCE_DYNAMIC_SIZE = 2u , MDBX_CP_DONT_FLUSH = 4u ,   MDBX_CP_THROTTLE_MVCC = 8u , MDBX_CP_DISPOSE_TXN = 16u , MDBX_CP_RENEW_TXN = 32u }
	Environment copy flags. More...
enum	MDBX_env_delete_mode_t { MDBX_ENV_JUST_DELETE = 0 , MDBX_ENV_ENSURE_UNUSED = 1 , MDBX_ENV_WAIT_FOR_UNUSED = 2 }
	Deletion modes for mdbx_env_delete(). More...

Functions
LIBMDBX_API int	mdbx_env_delete (const char *pathname, MDBX_env_delete_mode_t mode)
	Delete the environment's files in a proper and multiprocess-safe way.
LIBMDBX_API int	mdbx_env_deleteW (const wchar_t *pathname, MDBX_env_delete_mode_t mode)
	Delete the environment's files in a proper and multiprocess-safe way.
LIBMDBX_API int	mdbx_env_copy (MDBX_env *env, const char *dest, MDBX_copy_flags_t flags)
	Copy an MDBX environment to the specified path, with options.
LIBMDBX_API int	mdbx_txn_copy2pathname (MDBX_txn *txn, const char *dest, MDBX_copy_flags_t flags)
	Copy an MDBX environment by given read transaction to the specified path, with options.
LIBMDBX_API int	mdbx_env_copyW (MDBX_env *env, const wchar_t *dest, MDBX_copy_flags_t flags)
	Copy an MDBX environment to the specified path, with options.
LIBMDBX_API int	mdbx_txn_copy2pathnameW (MDBX_txn *txn, const wchar_t *dest, MDBX_copy_flags_t flags)
	Copy an MDBX environment by given read transaction to the specified path, with options.
LIBMDBX_API int	mdbx_env_copy2fd (MDBX_env *env, mdbx_filehandle_t fd, MDBX_copy_flags_t flags)
	Copy an environment to the specified file descriptor, with options.
LIBMDBX_API int	mdbx_txn_copy2fd (MDBX_txn *txn, mdbx_filehandle_t fd, MDBX_copy_flags_t flags)
	Copy an environment by given read transaction to the specified file descriptor, with options.
LIBMDBX_API int	mdbx_env_sync_ex (MDBX_env *env, bool force, bool nonblock)
	Flush the environment data buffers to disk.
int	mdbx_env_sync (MDBX_env *env)
	The shortcut to calling mdbx_env_sync_ex() with the force=true and nonblock=false arguments.
int	mdbx_env_sync_poll (MDBX_env *env)
	The shortcut to calling mdbx_env_sync_ex() with the force=false and nonblock=true arguments.
LIBMDBX_API int	mdbx_env_resurrect_after_fork (MDBX_env *env)
	Восстанавливает экземпляр среды в дочернем процессе после ветвления родительского процесса посредством fork() и родственных системных вызовов.
LIBMDBX_API int	mdbx_is_readahead_reasonable (size_t volume, intptr_t redundancy)
	Find out whether to use readahead or not, based on the given database size and the amount of available memory.
LIBMDBX_API int	mdbx_cursor_ignord (MDBX_cursor *cursor)
	Служебная функция для использования в утилитах.
LIBMDBX_API MDBX_cmp_func *	mdbx_get_keycmp (MDBX_db_flags_t flags)
	Returns default internal key's comparator for given table flags.
LIBMDBX_API MDBX_cmp_func *	mdbx_get_datacmp (MDBX_db_flags_t flags)
	Returns default internal data's comparator for given table flags.
LIBMDBX_API int	mdbx_reader_check (MDBX_env *env, int *dead)
	Check for stale entries in the reader lock table.
LIBMDBX_API int	mdbx_thread_register (const MDBX_env *env)
	Registers the current thread as a reader for the environment.
LIBMDBX_API int	mdbx_thread_unregister (const MDBX_env *env)
	Unregisters the current thread as a reader for the environment.
LIBMDBX_API int	mdbx_env_open_for_recoveryW (MDBX_env *env, const wchar_t *pathname, unsigned target_meta, bool writeable)
	Open an environment instance using specific meta-page for checking and recovery.

Detailed Description

Enumeration Type Documentation

MDBX_copy_flags_t

enum MDBX_copy_flags_t

Environment copy flags.

See also

mdbx_env_copy()

mdbx_env_copy2fd()

Enumerator
MDBX_CP_DEFAULTS
MDBX_CP_COMPACT	Copy with compactification: Omit free space from copy and renumber all pages sequentially
MDBX_CP_FORCE_DYNAMIC_SIZE	Force to make resizable copy, i.e. dynamic size instead of fixed
MDBX_CP_DONT_FLUSH	Don't explicitly flush the written data to an output media
MDBX_CP_THROTTLE_MVCC	Use read transaction parking during copying MVCC-snapshot See also mdbx_txn_park()
MDBX_CP_DISPOSE_TXN	Abort/dispose passed transaction after copy See also mdbx_txn_copy2fd() mdbx_txn_copy2pathname()
MDBX_CP_RENEW_TXN	Enable renew/restart read transaction in case it use outdated MVCC shapshot, otherwise the MDBX_MVCC_RETARDED will be returned See also mdbx_txn_copy2fd() mdbx_txn_copy2pathname()

MDBX_env_delete_mode_t

enum MDBX_env_delete_mode_t

Deletion modes for mdbx_env_delete().

See also

mdbx_env_delete()

Enumerator
MDBX_ENV_JUST_DELETE	Just delete the environment's files and directory if any. Note On POSIX systems, processes already working with the database will continue to work without interference until it close the environment. On Windows, the behavior of MDBX_ENV_JUST_DELETE is different because the system does not support deleting files that are currently memory mapped.
MDBX_ENV_ENSURE_UNUSED	Make sure that the environment is not being used by other processes, or return an error otherwise.
MDBX_ENV_WAIT_FOR_UNUSED	Wait until other processes closes the environment before deletion.

Function Documentation

mdbx_cursor_ignord()

LIBMDBX_API int mdbx_cursor_ignord

(

MDBX_cursor *

cursor

)

Служебная функция для использования в утилитах.

При использовании определяемых пользователем функций сравнения (aka custom comparison functions) проверка порядка ключей может приводить к неверным результатам и возврате ошибки MDBX_CORRUPTED.

Эта функция отключает контроль порядка следования ключей на страницах при чтении страниц БД для этого курсора, и таким образом, позволяет прочитать данные при отсутствии/недоступности использованных функций сравнения.

See also

avoid_custom_comparators

Returns

Результат операции сканирования, либо код ошибки.

mdbx_env_copy()

LIBMDBX_API int mdbx_env_copy	(	MDBX_env *	env,
		const char *	dest,
		MDBX_copy_flags_t	flags
	)

Copy an MDBX environment to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

On Windows the mdbx_env_copyW() is recommended to use.

See also

mdbx_env_copy2fd()

mdbx_txn_copy2pathname()

Parameters

[in]	env	An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
[in]	dest	The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
[in]	flags	Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
• MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
• MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
• MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
• MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

  See also

  mdbx_txn_park()

  Returns

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

mdbx_env_copy2fd()

LIBMDBX_API int mdbx_env_copy2fd	(	MDBX_env *	env,
		mdbx_filehandle_t	fd,
		MDBX_copy_flags_t	flags
	)

Copy an environment to the specified file descriptor, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

See also

mdbx_env_copy()

mdbx_txn_copy2fd()

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Fails if the environment has suffered a page leak and the destination file descriptor is associated with a pipe, socket, or FIFO.

Parameters

[in]	env	An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
[in]	fd	The file descriptor to write the copy to. It must have already been opened for Write access.
[in]	flags	Special options for this operation.

See also

mdbx_env_copy()

Returns

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

mdbx_env_copyW()

LIBMDBX_API int mdbx_env_copyW	(	MDBX_env *	env,
		const wchar_t *	dest,
		MDBX_copy_flags_t	flags
	)

Copy an MDBX environment to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

On Windows the mdbx_env_copyW() is recommended to use.

See also

mdbx_env_copy2fd()

mdbx_txn_copy2pathname()

Parameters

[in]	env	An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
[in]	dest	The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
[in]	flags	Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
• MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
• MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
• MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
• MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

  See also

  mdbx_txn_park()

  Returns

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

  Note

  Available only on Windows.

  See also

  mdbx_env_copy()

mdbx_env_delete()

LIBMDBX_API int mdbx_env_delete	(	const char *	pathname,
		MDBX_env_delete_mode_t	mode
	)

Delete the environment's files in a proper and multiprocess-safe way.

Note

On Windows the mdbx_env_deleteW() is recommended to use.

Parameters

[in]	pathname	The pathname for the database or the directory in which the database files reside.
[in]	mode	Specifies deletion mode for the environment. This parameter must be set to one of the constants described above in the MDBX_env_delete_mode_t section.

Note

The MDBX_ENV_JUST_DELETE don't supported on Windows since system unable to delete a memory-mapped files.

Returns

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

Return values

MDBX_RESULT_TRUE

No corresponding files or directories were found, so no deletion was performed.

mdbx_env_deleteW()

LIBMDBX_API int mdbx_env_deleteW	(	const wchar_t *	pathname,
		MDBX_env_delete_mode_t	mode
	)

Delete the environment's files in a proper and multiprocess-safe way.

Note

On Windows the mdbx_env_deleteW() is recommended to use.

Parameters

[in]	pathname	The pathname for the database or the directory in which the database files reside.
[in]	mode	Specifies deletion mode for the environment. This parameter must be set to one of the constants described above in the MDBX_env_delete_mode_t section.

Note

The MDBX_ENV_JUST_DELETE don't supported on Windows since system unable to delete a memory-mapped files.

Returns

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

Return values

MDBX_RESULT_TRUE

No corresponding files or directories were found, so no deletion was performed.

Note

Available only on Windows.

See also

mdbx_env_delete()

mdbx_env_open_for_recoveryW()

LIBMDBX_API int mdbx_env_open_for_recoveryW	(	MDBX_env *	env,
		const wchar_t *	pathname,
		unsigned	target_meta,
		bool	writeable
	)

Open an environment instance using specific meta-page for checking and recovery.

This function mostly of internal API for mdbx_chk utility and subject to change at any time. Do not use this function to avoid shooting your own leg(s).

Note

On Windows the mdbx_env_open_for_recoveryW() is recommended to use.

Available only on Windows.

See also

mdbx_env_open_for_recovery()

mdbx_env_resurrect_after_fork()

LIBMDBX_API int mdbx_env_resurrect_after_fork

(

MDBX_env *

env

)

Восстанавливает экземпляр среды в дочернем процессе после ветвления родительского процесса посредством fork() и родственных системных вызовов.

Без вызова mdbx_env_resurrect_after_fork() использование открытого экземпляра среды в дочернем процессе не возможно, включая все выполняющиеся на момент ветвления транзакции.

Выполняемые функцией действия можно рассматривать как повторное открытие БД в дочернем процессе, с сохранением заданных опций и адресов уже созданных экземпляров объектов связанных с API.

Note

Функция не доступна в ОС семейства Windows по причине отсутствия функционала ветвления процесса в API операционной системы.

Ветвление не оказывает влияния на состояние MDBX-среды в родительском процессе. Все транзакции, которые были в родительском процессе на момент ветвления, после ветвления в родительском процессе продолжат выполняться без помех. Но в дочернем процессе все соответствующие транзакции безальтернативно перестают быть валидными, а попытка их использования приведет к возврату ошибки или отправке SIGSEGV.

Использование экземпляра среды в дочернем процессе не возможно до вызова mdbx_env_resurrect_after_fork(), так как в результате ветвления у процесса меняется PID, значение которого используется для организации совместно работы с БД, в том числе, для отслеживания процессов/потоков выполняющих читающие транзакции связанные с соответствующими снимками данных. Все активные на момент ветвления транзакции не могут продолжаться в дочернем процессе, так как не владеют какими-либо блокировками или каким-либо снимком данных и не удерживает его от переработки при сборке мусора.

Функция mdbx_env_resurrect_after_fork() восстанавливает переданный экземпляр среды в дочернем процессе после ветвления, а именно: обновляет используемые системные идентификаторы, повторно открывает дескрипторы файлов, производит захват необходимых блокировок связанных с LCK- и DXB-файлами БД, восстанавливает отображения в память страницы БД, таблицы читателей и служебных/вспомогательных данных в память. Однако унаследованные от родительского процесса транзакции не восстанавливаются, прием пишущие и читающие транзакции обрабатываются по-разному:

• Пишущая транзакция, если таковая была на момент ветвления, прерывается в дочернем процессе с освобождение связанных с ней ресурсов, включая все вложенные транзакции.
• Читающие же транзакции, если таковые были в родительском процессе, в дочернем процессе логически прерываются, но без освобождения ресурсов. Поэтому необходимо обеспечить вызов mdbx_txn_abort() для каждой такой читающей транзакций в дочернем процессе, либо смириться с утечкой ресурсов до завершения дочернего процесса.

Причина не-освобождения ресурсов читающих транзакций в том, что исторически MDBX не ведет какой-либо общий список экземпляров читающих, так как это не требуется для штатных режимов работы, но требует использования атомарных операций или дополнительных объектов синхронизации при создании/разрушении экземпляров MDBX_txn.

Вызов mdbx_env_resurrect_after_fork() без ветвления, не в дочернем процессе, либо повторные вызовы не приводят к каким-либо действиям или изменениям.

Parameters

[in,out]

env

Экземпляр среды созданный функцией mdbx_env_create().

Returns

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

Return values

MDBX_BUSY	В родительском процессе БД была открыта в режиме MDBX_EXCLUSIVE.
MDBX_EBADSIGN	При повреждении сигнатуры экземпляра объекта, а также в случае одновременного вызова mdbx_env_resurrect_after_fork() из разных потоков.
MDBX_PANIC	Произошла критическая ошибка при восстановлении экземпляра среды, либо такая ошибка уже была до вызова функции.

mdbx_env_sync()

int mdbx_env_sync ( MDBX_env *  env )

inline

The shortcut to calling mdbx_env_sync_ex() with the force=true and nonblock=false arguments.

mdbx_env_sync_ex()

LIBMDBX_API int mdbx_env_sync_ex	(	MDBX_env *	env,
		bool	force,
		bool	nonblock
	)

Flush the environment data buffers to disk.

Unless the environment was opened with no-sync flags (MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC and MDBX_UTTERLY_NOSYNC), then data is always written an flushed to disk when mdbx_txn_commit() is called. Otherwise mdbx_env_sync() may be called to manually write and flush unsynced data to disk.

Besides, mdbx_env_sync_ex() with argument force=false may be used to provide polling mode for lazy/asynchronous sync in conjunction with mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod().

Note

This call is not valid if the environment was opened with MDBX_RDONLY.

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[in]	force	If non-zero, force a flush. Otherwise, If force is zero, then will run in polling mode, i.e. it will check the thresholds that were set mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod() and perform flush if at least one of the thresholds is reached.
[in]	nonblock	Don't wait if write transaction is running by other thread.

Returns

A non-zero error value on failure and MDBX_RESULT_TRUE or 0 on success. The MDBX_RESULT_TRUE means no data pending for flush to disk, and 0 otherwise. Some possible errors are:

Return values

MDBX_EACCES	The environment is read-only.
MDBX_BUSY	The environment is used by other thread and nonblock=true.
MDBX_EINVAL	An invalid parameter was specified.
MDBX_EIO	An error occurred during the flushing/writing data to a storage medium/disk.

mdbx_env_sync_poll()

int mdbx_env_sync_poll ( MDBX_env *  env )

inline

The shortcut to calling mdbx_env_sync_ex() with the force=false and nonblock=true arguments.

mdbx_get_datacmp()

LIBMDBX_API MDBX_cmp_func * mdbx_get_datacmp

(

MDBX_db_flags_t

flags

)

Returns default internal data's comparator for given table flags.

mdbx_get_keycmp()

LIBMDBX_API MDBX_cmp_func * mdbx_get_keycmp

(

MDBX_db_flags_t

flags

)

Returns default internal key's comparator for given table flags.

mdbx_is_readahead_reasonable()

LIBMDBX_API int mdbx_is_readahead_reasonable	(	size_t	volume,
		intptr_t	redundancy
	)

Find out whether to use readahead or not, based on the given database size and the amount of available memory.

Parameters

[in]	volume	The expected database size in bytes.
[in]	redundancy	Additional reserve or overload in case of negative value.

Returns

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return values

MDBX_RESULT_TRUE	Readahead is reasonable.
MDBX_RESULT_FALSE	Readahead is NOT reasonable, i.e. MDBX_NORDAHEAD is useful to open environment by mdbx_env_open().
Otherwise	the error code.

mdbx_reader_check()

LIBMDBX_API int mdbx_reader_check	(	MDBX_env *	env,
		int *	dead
	)

Check for stale entries in the reader lock table.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	dead	Number of stale slots that were cleared.

Returns

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered.

mdbx_thread_register()

LIBMDBX_API int mdbx_thread_register

(

const MDBX_env *

env

)

Registers the current thread as a reader for the environment.

To perform read operations without blocking, a reader slot must be assigned for each thread. However, this assignment requires a short-term lock acquisition which is performed automatically. This function allows you to assign the reader slot in advance and thus avoid capturing the blocker when the read transaction starts firstly from current thread.

See also

mdbx_thread_unregister()

Note

Threads are registered automatically the first time a read transaction starts. Therefore, there is no need to use this function, except in special cases.

Parameters

[in]

env

An environment handle returned by mdbx_env_create().

Returns

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is already registered.

mdbx_thread_unregister()

LIBMDBX_API int mdbx_thread_unregister

(

const MDBX_env *

env

)

Unregisters the current thread as a reader for the environment.

To perform read operations without blocking, a reader slot must be assigned for each thread. However, the assigned reader slot will remain occupied until the thread ends or the environment closes. This function allows you to explicitly release the assigned reader slot.

See also

mdbx_thread_register()

Parameters

[in]

env

An environment handle returned by mdbx_env_create().

Returns

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is not registered or already unregistered.

mdbx_txn_copy2fd()

LIBMDBX_API int mdbx_txn_copy2fd	(	MDBX_txn *	txn,
		mdbx_filehandle_t	fd,
		MDBX_copy_flags_t	flags
	)

Copy an environment by given read transaction to the specified file descriptor, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

See also

mdbx_txn_copy2pathname()

mdbx_env_copy2fd()

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Fails if the environment has suffered a page leak and the destination file descriptor is associated with a pipe, socket, or FIFO.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	fd	The file descriptor to write the copy to. It must have already been opened for Write access.
[in]	flags	Special options for this operation.

See also

mdbx_env_copy()

Returns

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

mdbx_txn_copy2pathname()

LIBMDBX_API int mdbx_txn_copy2pathname	(	MDBX_txn *	txn,
		const char *	dest,
		MDBX_copy_flags_t	flags
	)

Copy an MDBX environment by given read transaction to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

On Windows the mdbx_txn_copy2pathnameW() is recommended to use.

See also

mdbx_txn_copy2fd()

mdbx_env_copy()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dest	The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
[in]	flags	Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
• MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
• MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
• MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
• MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

  See also

  mdbx_txn_park()

  Returns

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

mdbx_txn_copy2pathnameW()

LIBMDBX_API int mdbx_txn_copy2pathnameW	(	MDBX_txn *	txn,
		const wchar_t *	dest,
		MDBX_copy_flags_t	flags
	)

Copy an MDBX environment by given read transaction to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

On Windows the mdbx_txn_copy2pathnameW() is recommended to use.

See also

mdbx_txn_copy2fd()

mdbx_env_copy()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dest	The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
[in]	flags	Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:

• MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
• MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
• MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
• MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
• MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

  See also

  mdbx_txn_park()

  Returns

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

  Note

  Available only on Windows.

  See also

  mdbx_txn_copy2pathname()