Version 12.0.0
All Classes Functions Variables Typedefs Enumerations Enumerator Modules Pages
WT_CONNECTION Struct Reference

A connection to a WiredTiger database. More...

Public Member Functions

int close (WT_CONNECTION *connection, const char *config)
 Close a connection. More...
 
int reconfigure (WT_CONNECTION *connection, const char *config)
 Reconfigure a connection handle. More...
 
const char * get_home (WT_CONNECTION *connection)
 The home directory of the connection. More...
 
int compile_configuration (WT_CONNECTION *connection, const char *method, const char *str, const char **compiled)
 Compile a configuration string to be used with an API. More...
 
int configure_method (WT_CONNECTION *connection, const char *method, const char *uri, const char *config, const char *type, const char *check)
 Add configuration options for a method. More...
 
int is_new (WT_CONNECTION *connection)
 Return if opening this handle created the database. More...
 
Session handles
int open_session (WT_CONNECTION *connection, WT_EVENT_HANDLER *event_handler, const char *config, WT_SESSION **sessionp)
 Open a session. More...
 
Transactions
int query_timestamp (WT_CONNECTION *connection, char *hex_timestamp, const char *config)
 Query the global transaction timestamp state. More...
 
int set_timestamp (WT_CONNECTION *connection, const char *config)
 Set a global transaction timestamp. More...
 
int rollback_to_stable (WT_CONNECTION *connection, const char *config)
 Rollback tables to an earlier point in time, discarding all updates to checkpoint durable tables that have commit times more recent than the current global stable timestamp. More...
 
Extensions
int load_extension (WT_CONNECTION *connection, const char *path, const char *config)
 Load an extension. More...
 
int add_data_source (WT_CONNECTION *connection, const char *prefix, WT_DATA_SOURCE *data_source, const char *config)
 Add a custom data source. More...
 
int add_collator (WT_CONNECTION *connection, const char *name, WT_COLLATOR *collator, const char *config)
 Add a custom collation function. More...
 
int add_compressor (WT_CONNECTION *connection, const char *name, WT_COMPRESSOR *compressor, const char *config)
 Add a compression function. More...
 
int add_encryptor (WT_CONNECTION *connection, const char *name, WT_ENCRYPTOR *encryptor, const char *config)
 Add an encryption function. More...
 
int add_extractor (WT_CONNECTION *connection, const char *name, WT_EXTRACTOR *extractor, const char *config)
 Add a custom extractor for index keys or column groups. More...
 
int set_file_system (WT_CONNECTION *connection, WT_FILE_SYSTEM *fs, const char *config)
 Configure a custom file system. More...
 
WT_EXTENSION_APIget_extension_api (WT_CONNECTION *wt_conn)
 Return a reference to the WiredTiger extension functions. More...
 

Detailed Description

A connection to a WiredTiger database.

The connection may be opened within the same address space as the caller or accessed over a socket connection.

Most applications will open a single connection to a database for each process. The first process to open a connection to a database will access the database in its own address space. Subsequent connections (if allowed) will communicate with the first process over a socket connection to perform their operations.

Thread safety: A WT_CONNECTION handle may be shared between threads. See Multithreading for more information.

Examples
ex_access.c, ex_backup.c, ex_backup_block.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extra_diagnostics.c, ex_extractor.c, ex_file_system.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, nop_encrypt.c, rotn_encrypt.c, and sodium_encrypt.c.

Member Function Documentation

◆ add_collator()

int WT_CONNECTION::add_collator ( WT_CONNECTION connection,
const char *  name,
WT_COLLATOR collator,
const char *  config 
)

Add a custom collation function.

The application must first implement the WT_COLLATOR interface and then register the implementation with WiredTiger:

static WT_COLLATOR my_collator = {my_compare, NULL, NULL};
error_check(conn->add_collator(conn, "my_collator", &my_collator, NULL));
Parameters
connectionthe connection handle
namethe name of the collation to be used in calls to WT_SESSION::create, may not be "none"
collatorthe application-supplied collation handler
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_extending.c.

◆ add_compressor()

int WT_CONNECTION::add_compressor ( WT_CONNECTION connection,
const char *  name,
WT_COMPRESSOR compressor,
const char *  config 
)

Add a compression function.

The application must first implement the WT_COMPRESSOR interface and then register the implementation with WiredTiger:

/* Local compressor structure. */
typedef struct {
WT_COMPRESSOR compressor; /* Must come first */
WT_EXTENSION_API *wt_api; /* Extension API */
unsigned long nop_calls; /* Count of calls */
} NOP_COMPRESSOR;
/*
* wiredtiger_extension_init --
* A simple shared library compression example.
*/
int
{
NOP_COMPRESSOR *nop_compressor;
int ret;
(void)config; /* Unused parameters */
if ((nop_compressor = calloc(1, sizeof(NOP_COMPRESSOR))) == NULL)
return (errno);
/*
* Allocate a local compressor structure, with a WT_COMPRESSOR structure as the first field,
* allowing us to treat references to either type of structure as a reference to the other type.
*
* Heap memory (not static), because it can support multiple databases.
*/
nop_compressor->compressor.compress = nop_compress;
nop_compressor->compressor.decompress = nop_decompress;
nop_compressor->compressor.pre_size = nop_pre_size;
nop_compressor->compressor.terminate = nop_terminate;
nop_compressor->wt_api = connection->get_extension_api(connection);
/* Load the compressor */
if ((ret = connection->add_compressor(
connection, "nop", (WT_COMPRESSOR *)nop_compressor, NULL)) == 0)
return (0);
free(nop_compressor);
return (ret);
}
Parameters
connectionthe connection handle
namethe name of the compression function to be used in calls to WT_SESSION::create, may not be "none"
compressorthe application-supplied compression handler
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ add_data_source()

int WT_CONNECTION::add_data_source ( WT_CONNECTION connection,
const char *  prefix,
WT_DATA_SOURCE data_source,
const char *  config 
)

Add a custom data source.

See Custom Data Sources for more information.

The application must first implement the WT_DATA_SOURCE interface and then register the implementation with WiredTiger:

static WT_DATA_SOURCE my_dsrc = {my_alter, my_create, my_compact, my_drop, my_open_cursor,
my_rename, my_salvage, my_size, my_truncate, my_range_truncate, my_verify, my_checkpoint,
my_terminate, my_lsm_pre_merge};
error_check(conn->add_data_source(conn, "dsrc:", &my_dsrc, NULL));
Parameters
connectionthe connection handle
prefixthe URI prefix for this data source, e.g., "file:"
data_sourcethe application-supplied implementation of WT_DATA_SOURCE to manage this data source.
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ add_encryptor()

int WT_CONNECTION::add_encryptor ( WT_CONNECTION connection,
const char *  name,
WT_ENCRYPTOR encryptor,
const char *  config 
)

Add an encryption function.

The application must first implement the WT_ENCRYPTOR interface and then register the implementation with WiredTiger:

/* Local encryptor structure. */
typedef struct {
WT_ENCRYPTOR encryptor; /* Must come first */
WT_EXTENSION_API *wt_api; /* Extension API */
unsigned long nop_calls; /* Count of calls */
} NOP_ENCRYPTOR;
/*
* wiredtiger_extension_init --
* A simple shared library encryption example.
*/
int
{
NOP_ENCRYPTOR *nop_encryptor;
int ret;
(void)config; /* Unused parameters */
if ((nop_encryptor = calloc(1, sizeof(NOP_ENCRYPTOR))) == NULL)
return (errno);
/*
* Allocate a local encryptor structure, with a WT_ENCRYPTOR structure as the first field,
* allowing us to treat references to either type of structure as a reference to the other type.
*
* Heap memory (not static), because it can support multiple databases.
*/
nop_encryptor->encryptor.encrypt = nop_encrypt;
nop_encryptor->encryptor.decrypt = nop_decrypt;
nop_encryptor->encryptor.sizing = nop_sizing;
nop_encryptor->encryptor.customize = nop_customize;
nop_encryptor->encryptor.terminate = nop_terminate;
nop_encryptor->wt_api = connection->get_extension_api(connection);
/* Load the encryptor */
if ((ret = connection->add_encryptor(connection, "nop", (WT_ENCRYPTOR *)nop_encryptor, NULL)) ==
0)
return (0);
free(nop_encryptor);
return (ret);
}
Parameters
connectionthe connection handle
namethe name of the encryption function to be used in calls to WT_SESSION::create, may not be "none"
encryptorthe application-supplied encryption handler
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_encrypt.c, nop_encrypt.c, rotn_encrypt.c, and sodium_encrypt.c.

◆ add_extractor()

int WT_CONNECTION::add_extractor ( WT_CONNECTION connection,
const char *  name,
WT_EXTRACTOR extractor,
const char *  config 
)

Add a custom extractor for index keys or column groups.

The application must first implement the WT_EXTRACTOR interface and then register the implementation with WiredTiger:

static WT_EXTRACTOR my_extractor = {my_extract, NULL, NULL};
error_check(conn->add_extractor(conn, "my_extractor", &my_extractor, NULL));
Parameters
connectionthe connection handle
namethe name of the extractor to be used in calls to WT_SESSION::create, may not be "none"
extractorthe application-supplied extractor
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_extractor.c.

◆ close()

int WT_CONNECTION::close ( WT_CONNECTION connection,
const char *  config 
)

Close a connection.

Any open sessions will be closed. This will release the resources associated with the session handle, including rolling back any active transactions and closing any cursors that remain open in the session.

error_check(conn->close(conn, NULL));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
leak_memorydon't free memory during close.a boolean flag; default false.
use_timestampby default, create the close checkpoint as of the last stable timestamp if timestamps are in use, or all current updates if there is no stable timestamp set. If false, this option generates a checkpoint with all updates.a boolean flag; default true.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_access.c, ex_backup.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_file_system.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.

◆ compile_configuration()

int WT_CONNECTION::compile_configuration ( WT_CONNECTION connection,
const char *  method,
const char *  str,
const char **  compiled 
)

Compile a configuration string to be used with an API.

The string returned by this method can be used with the indicated API call as its configuration argument. Precompiled strings should be used where configuration parsing has proved to be a performance bottleneck. The lifetime of a configuration string ends when the connection is closed. The number of compilation strings that can be made is limited by the compile_configuration_count configuration in wiredtiger_open .

Configuration strings containing 'd' or 's' can have values bound, see WT_SESSION::bind_configuration.

This API may change in future releases.

Parameters
connectionthe connection handle
methodthe API to the configuration string applies to, e.g. "WT_SESSION.open_cursor"
strthe configuration string to compile
compiledthe returned configuration string
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ configure_method()

int WT_CONNECTION::configure_method ( WT_CONNECTION connection,
const char *  method,
const char *  uri,
const char *  config,
const char *  type,
const char *  check 
)

Add configuration options for a method.

See Creating data-specific configuration strings for more information.

/*
* Applications opening a cursor for the data-source object "my_data" have an additional
* configuration option "entries", which is an integer type, defaults to 5, and must be an
* integer between 1 and 10.
*
* The method being configured is specified using a concatenation of the handle name, a period
* and the method name.
*/
error_check(conn->configure_method(
conn, "WT_SESSION.open_cursor", "my_data:", "entries=5", "int", "min=1,max=10"));
/*
* Applications opening a cursor for the data-source object "my_data" have an additional
* configuration option "devices", which is a list of strings.
*/
error_check(
conn->configure_method(conn, "WT_SESSION.open_cursor", "my_data:", "devices", "list", NULL));
Parameters
connectionthe connection handle
methodthe method being configured
urithe object type or NULL for all object types
configthe additional configuration's name and default value
typethe additional configuration's type (must be one of "boolean"\, "int", "list" or "string")
checkthe additional configuration check string, or NULL if none
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ get_extension_api()

WT_EXTENSION_API* WT_CONNECTION::get_extension_api ( WT_CONNECTION wt_conn)

Return a reference to the WiredTiger extension functions.

#include <wiredtiger_ext.h>
static WT_EXTENSION_API *wt_api;
static void
my_data_source_init(WT_CONNECTION *connection)
{
wt_api = connection->get_extension_api(connection);
}
Parameters
wt_connthe WT_CONNECTION handle
Returns
a reference to a WT_EXTENSION_API structure.
Examples
ex_encrypt.c, ex_file_system.c, nop_encrypt.c, rotn_encrypt.c, and sodium_encrypt.c.

◆ get_home()

const char* WT_CONNECTION::get_home ( WT_CONNECTION connection)

The home directory of the connection.

printf("The database home is %s\n", conn->get_home(conn));
Parameters
connectionthe connection handle
Returns
a pointer to a string naming the home directory

◆ is_new()

int WT_CONNECTION::is_new ( WT_CONNECTION connection)

Return if opening this handle created the database.

if (conn->is_new(conn)) {
/* First time initialization. */
}
Parameters
connectionthe connection handle
Returns
false (zero) if the connection existed before the call to wiredtiger_open, true (non-zero) if it was created by opening this handle.

◆ load_extension()

int WT_CONNECTION::load_extension ( WT_CONNECTION connection,
const char *  path,
const char *  config 
)

Load an extension.

error_check(conn->load_extension(conn, "my_extension.dll", NULL));
error_check(conn->load_extension(
conn, "datasource/libdatasource.so", "config=[device=/dev/sd1,alignment=64]"));
Parameters
connectionthe connection handle
paththe filename of the extension module, or "local" to search the current application binary for the initialization function, see Extending WiredTiger for more details.
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
configconfiguration string passed to the entry point of the extension as its WT_CONFIG_ARG argument.a string; default empty.
early_loadwhether this extension should be loaded at the beginning of wiredtiger_open. Only applicable to extensions loaded via the wiredtiger_open configurations string.a boolean flag; default false.
entrythe entry point of the extension, called to initialize the extension when it is loaded. The signature of the function must match wiredtiger_extension_init.a string; default wiredtiger_extension_init.
terminatean optional function in the extension that is called before the extension is unloaded during WT_CONNECTION::close. The signature of the function must match wiredtiger_extension_terminate.a string; default wiredtiger_extension_terminate.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ open_session()

int WT_CONNECTION::open_session ( WT_CONNECTION connection,
WT_EVENT_HANDLER event_handler,
const char *  config,
WT_SESSION **  sessionp 
)

Open a session.

WT_SESSION *session;
error_check(conn->open_session(conn, NULL, NULL, &session));
Parameters
connectionthe connection handle
event_handlerAn event handler. If NULL, the connection's event handler is used. See Message handling using the WT_EVENT_HANDLER for more information.
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
cache_cursorsenable caching of cursors for reuse. Any calls to WT_CURSOR::close for a cursor created in this session will mark the cursor as cached and keep it available to be reused for later calls to WT_SESSION::open_cursor. Cached cursors may be eventually closed. This value is inherited from wiredtiger_open cache_cursors.a boolean flag; default true.
cache_max_wait_msthe maximum number of milliseconds an application thread will wait for space to be available in cache before giving up. Default value will be the global setting of the connection config.an integer greater than or equal to 0; default 0.
debug = (configure debug specific behavior on a session. Generally only used for internal testing purposes.a set of related configuration options defined as follows.
    checkpoint_fail_before_turtle_updateFail before writing a turtle file at the end of a checkpoint.a boolean flag; default false.
    release_evict_pageConfigure the session to evict the page when it is released and no longer needed.a boolean flag; default false.
)
ignore_cache_sizewhen set, operations performed by this session ignore the cache size and are not blocked when the cache is full. Note that use of this option for operations that create cache pressure can starve ordinary sessions that obey the cache size.a boolean flag; default false.
isolationthe default isolation level for operations in this session.a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default snapshot.
prefetch = (Enable automatic detection of scans by applications, and attempt to pre-fetch future content into the cache.a set of related configuration options defined as follows.
    enabledwhether pre-fetch is enabled for this session.a boolean flag; default false.
)
[out]sessionpthe new session handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_access.c, ex_backup.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_file_system.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.

◆ query_timestamp()

int WT_CONNECTION::query_timestamp ( WT_CONNECTION connection,
char *  hex_timestamp,
const char *  config 
)

Query the global transaction timestamp state.

char timestamp_buf[2 * sizeof(uint64_t) + 1];
error_check(session->timestamp_transaction(session, "commit_timestamp=2a"));
error_check(session->commit_transaction(session, NULL));
error_check(conn->query_timestamp(conn, timestamp_buf, "get=all_durable"));
Parameters
connectionthe connection handle
[out]hex_timestampa buffer that will be set to the hexadecimal encoding of the timestamp being queried. Must be large enough to hold a NUL terminated, hex-encoded 8B timestamp (17 bytes).
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
getspecify which timestamp to query: all_durable returns the largest timestamp such that all timestamps up to and including that value have been committed (possibly bounded by the application-set durable timestamp); backup_checkpoint returns the stable timestamp of the checkpoint pinned for an open backup cursor; last_checkpoint returns the timestamp of the most recent stable checkpoint; oldest_timestamp returns the most recent oldest_timestamp set with WT_CONNECTION::set_timestamp; oldest_reader returns the minimum of the read timestamps of all active readers; pinned returns the minimum of the oldest_timestamp and the read timestamps of all active readers; recovery returns the timestamp of the most recent stable checkpoint taken prior to a shutdown; stable_timestamp returns the most recent stable_timestamp set with WT_CONNECTION::set_timestamp. (The oldest and stable arguments are deprecated short-hand for oldest_timestamp and stable_timestamp, respectively.) See Managing the global timestamp state.a string, chosen from the following options: "all_durable", "backup_checkpoint", "last_checkpoint", "oldest", "oldest_reader", "oldest_timestamp", "pinned", "recovery", "stable", "stable_timestamp"; default all_durable.

A timestamp of 0 is returned if the timestamp is not available or has not been set.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ reconfigure()

int WT_CONNECTION::reconfigure ( WT_CONNECTION connection,
const char *  config 
)

Reconfigure a connection handle.

error_check(conn->reconfigure(conn, "eviction_target=75"));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
block_cache = (block cache configuration options.a set of related configuration options defined as follows.
    blkcache_eviction_aggressionseconds an unused block remains in the cache before it is evicted.an integer between 1 and 7200; default 1800.
    cache_on_checkpointcache blocks written by a checkpoint.a boolean flag; default true.
    cache_on_writescache blocks as they are written (other than checkpoint blocks).a boolean flag; default true.
     enabledenable block cache.a boolean flag; default false.
    full_targetthe fraction of the block cache that must be full before eviction will remove unused blocks.an integer between 30 and 100; default 95.
    hashsizenumber of buckets in the hashtable that keeps track of blocks.an integer between 512 and 256K; default 32768.
    max_percent_overheadmaximum tolerated overhead expressed as the number of blocks added and removed as percent of blocks looked up; cache population and eviction will be suppressed if the overhead exceeds the threshold.an integer between 1 and 500; default 10.
    nvram_paththe absolute path to the file system mounted on the NVRAM device.a string; default empty.
    percent_file_in_drambypass cache for a file if the set percentage of the file fits in system DRAM (as specified by block_cache.system_ram).an integer between 0 and 100; default 50.
    sizemaximum memory to allocate for the block cache.an integer between 0 and 10TB; default 0.
    system_ramthe bytes of system DRAM available for caching filesystem blocks.an integer between 0 and 1024GB; default 0.
    typecache location: DRAM or NVRAM.a string; default empty.
)
cache_max_wait_msthe maximum number of milliseconds an application thread will wait for space to be available in cache before giving up. Default will wait forever.an integer greater than or equal to 0; default 0.
cache_overheadassume the heap allocator overhead is the specified percentage, and adjust the cache usage by that amount (for example, if there is 10GB of data in cache, a percentage of 10 means WiredTiger treats this as 11GB). This value is configurable because different heap allocators have different overhead and different workloads will have different heap allocation sizes and patterns, therefore applications may need to adjust this value based on allocator choice and behavior in measured workloads.an integer between 0 and 30; default 8.
cache_sizemaximum heap memory to allocate for the cache. A database should configure either cache_size or shared_cache but not both.an integer between 1MB and 10TB; default 100MB.
cache_stuck_timeout_msthe number of milliseconds to wait before a stuck cache times out in diagnostic mode. Default will wait for 5 minutes, 0 will wait forever.an integer greater than or equal to 0; default 300000.
checkpoint = (periodically checkpoint the database. Enabling the checkpoint server uses a session from the configured session_max.a set of related configuration options defined as follows.
    log_sizewait for this amount of log record bytes to be written to the log between each checkpoint. If non-zero, this value will use a minimum of the log file size. A database can configure both log_size and wait to set an upper bound for checkpoints; setting this value above 0 configures periodic checkpoints.an integer between 0 and 2GB; default 0.
    waitseconds to wait between each checkpoint; setting this value above 0 configures periodic checkpoints.an integer between 0 and 100000; default 0.
)
checkpoint_cleanup = (periodically checkpoint cleanup the database.a set of related configuration options defined as follows.
    methodcontrol how aggressively obsolete content is removed by reading the internal pages. Default to none, which means no additional work is done to find obsolete content.a string, chosen from the following options: "none", "reclaim_space"; default none.
    waitseconds to wait between each checkpoint cleanup.an integer between 60 and 100000; default 300.
)
chunk_cache = (chunk cache reconfiguration options.a set of related configuration options defined as follows.
    pinnedList of "table:" URIs exempt from cache eviction. Capacity config overrides this, tables exceeding capacity will not be fully retained. Table names can appear in both this and the preload list, but not in both this and the exclude list. Duplicate names are allowed.a list of strings; default empty.
)
compatibility = (set compatibility version of database. Changing the compatibility version requires that there are no active operations for the duration of the call.a set of related configuration options defined as follows.
    releasecompatibility release version string.a string; default empty.
)
debug_mode = (control the settings of various extended debugging features.a set of related configuration options defined as follows.
     background_compactif true, background compact aggressively removes compact statistics for a file and decreases the max amount of time a file can be skipped for.a boolean flag; default false.
    checkpoint_retentionadjust log removal to retain the log records of this number of checkpoints. Zero or one means perform normal removal.an integer between 0 and 1024; default 0.
    configurationif true, display invalid cache configuration warnings.a boolean flag; default false.
     corruption_abortif true and built in diagnostic mode, dump core in the case of data corruption.a boolean flag; default true.
    cursor_copyif true, use the system allocator to make a copy of any data returned by a cursor operation and return the copy instead. The copy is freed on the next cursor operation. This allows memory sanitizers to detect inappropriate references to memory owned by cursors.a boolean flag; default false.
    cursor_repositionif true, for operations with snapshot isolation the cursor temporarily releases any page that requires force eviction, then repositions back to the page for further operations. A page release encourages eviction of hot or large pages, which is more likely to succeed without a cursor keeping the page pinned.a boolean flag; default false.
     evictionif true, modify internal algorithms to change skew to force history store eviction to happen more aggressively. This includes but is not limited to not skewing newest, not favoring leaf pages, and modifying the eviction score mechanism.a boolean flag; default false.
    eviction_checkpoint_ts_orderingif true, act as if eviction is being run in parallel to checkpoint. We should return EBUSY in eviction if we detect any timestamp ordering issue.a boolean flag; default false.
    log_retentionadjust log removal to retain at least this number of log files. (Warning: this option can remove log files required for recovery if no checkpoints have yet been done and the number of log files exceeds the configured value. As WiredTiger cannot detect the difference between a system that has not yet checkpointed and one that will never checkpoint, it might discard log files before any checkpoint is done.) Ignored if set to 0.an integer between 0 and 1024; default 0.
    realloc_exactif true, reallocation of memory will only provide the exact amount requested. This will help with spotting memory allocation issues more easily.a boolean flag; default false.
     realloc_mallocif true, every realloc call will force a new memory allocation by using malloc.a boolean flag; default false.
    rollback_errorreturn a WT_ROLLBACK error from a transaction operation about every Nth operation to simulate a collision.an integer between 0 and 10M; default 0.
    slow_checkpointif true, slow down checkpoint creation by slowing down internal page processing.a boolean flag; default false.
    stress_skiplistConfigure various internal parameters to encourage race conditions and other issues with internal skip lists, e.g. using a more dense representation.a boolean flag; default false.
     table_loggingif true, write transaction related information to the log for all operations, even operations for tables with logging turned off. This additional logging information is intended for debugging and is informational only, that is, it is ignored during recovery.a boolean flag; default false.
     tiered_flush_error_continueon a write to tiered storage, continue when an error occurs.a boolean flag; default false.
    update_restore_evictif true, control all dirty page evictions through forcing update restore eviction.a boolean flag; default false.
)
error_prefixprefix string for error messages.a string; default empty.
eviction = (eviction configuration options.a set of related configuration options defined as follows.
    evict_sample_inmemIf no in-memory ref is found on the root page, attempt to locate a random in-memory page by examining all entries on the root page.a boolean flag; default true.
     threads_maxmaximum number of threads WiredTiger will start to help evict pages from cache. The number of threads started will vary depending on the current eviction load. Each eviction worker thread uses a session from the configured session_max.an integer between 1 and 20; default 8.
    threads_minminimum number of threads WiredTiger will start to help evict pages from cache. The number of threads currently running will vary depending on the current eviction load.an integer between 1 and 20; default 1.
)
eviction_checkpoint_targetperform eviction at the beginning of checkpoints to bring the dirty content in cache to this level. It is a percentage of the cache size if the value is within the range of 0 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size. Ignored if set to zero.an integer between 0 and 10TB; default 1.
eviction_dirty_targetperform eviction in worker threads when the cache contains at least this much dirty content. It is a percentage of the cache size if the value is within the range of 1 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size and has to be lower than its counterpart eviction_dirty_trigger.an integer between 1 and 10TB; default 5.
eviction_dirty_triggertrigger application threads to perform eviction when the cache contains at least this much dirty content. It is a percentage of the cache size if the value is within the range of 1 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size and has to be greater than its counterpart eviction_dirty_target. This setting only alters behavior if it is lower than eviction_trigger.an integer between 1 and 10TB; default 20.
eviction_targetperform eviction in worker threads when the cache contains at least this much content. It is a percentage of the cache size if the value is within the range of 10 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size and has to be lower than its counterpart eviction_trigger.an integer between 10 and 10TB; default 80.
eviction_triggertrigger application threads to perform eviction when the cache contains at least this much content. It is a percentage of the cache size if the value is within the range of 10 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size and has to be greater than its counterpart eviction_target.an integer between 10 and 10TB; default 95.
eviction_updates_targetperform eviction in worker threads when the cache contains at least this many bytes of updates. It is a percentage of the cache size if the value is within the range of 0 to 100 or an absolute size when greater than 100. Calculated as half of eviction_dirty_target by default. The value is not allowed to exceed the cache_size and has to be lower than its counterpart eviction_updates_trigger.an integer between 0 and 10TB; default 0.
eviction_updates_triggertrigger application threads to perform eviction when the cache contains at least this many bytes of updates. It is a percentage of the cache size if the value is within the range of 1 to 100 or an absolute size when greater than 100. Calculated as half of eviction_dirty_trigger by default. The value is not allowed to exceed the cache_size and has to be greater than its counterpart eviction_updates_target. This setting only alters behavior if it is lower than eviction_trigger.an integer between 0 and 10TB; default 0.
extra_diagnosticsenable additional diagnostics in WiredTiger. These additional diagnostics include diagnostic assertions that can cause WiredTiger to abort when an invalid state is detected. Options are given as a list, such as "extra_diagnostics=[out_of_order,visibility]". Choosing all enables all assertions. When WiredTiger is compiled with HAVE_DIAGNOSTIC=1 all assertions are enabled and cannot be reconfigured.a list, with values chosen from the following options: "all", "checkpoint_validate", "cursor_check", "disk_validate", "eviction_check", "generation_check", "hs_validate", "key_out_of_order", "log_validate", "prepared", "slow_operation", "txn_visibility"; default [].
file_manager = (control how file handles are managed.a set of related configuration options defined as follows.
     close_handle_minimumnumber of handles open before the file manager will look for handles to close.an integer greater than or equal to 0; default 250.
    close_idle_timeamount of time in seconds a file handle needs to be idle before attempting to close it. A setting of 0 means that idle handles are not closed.an integer between 0 and 100000; default 30.
    close_scan_intervalinterval in seconds at which to check for files that are inactive and close them.an integer between 1 and 100000; default 10.
)
generation_drain_timeout_msthe number of milliseconds to wait for a resource to drain before timing out in diagnostic mode. Default will wait for 4 minutes, 0 will wait forever.an integer greater than or equal to 0; default 240000.
heuristic_controls = (control the behavior of various optimizations. This is primarily used as a mechanism for rolling out changes to internal heuristics while providing a mechanism for quickly reverting to prior behavior in the field.a set of related configuration options defined as follows.
     checkpoint_cleanup_obsolete_tw_pages_dirty_maxmaximum number of obsolete time window pages that can be marked as dirty per btree in a single checkpoint by the checkpoint cleanup.an integer between 0 and 100000; default 100.
     eviction_obsolete_tw_pages_dirty_maxmaximum number of obsolete time window pages that can be marked dirty per btree in a single checkpoint by the eviction threads.an integer between 0 and 100000; default 100.
    obsolete_tw_btree_maxmaximum number of btrees that can be checked for obsolete time window cleanup in a single checkpoint.an integer between 0 and 500000; default 100.
)
history_store = (history store configuration options.a set of related configuration options defined as follows.
    file_maxthe maximum number of bytes that WiredTiger is allowed to use for its history store mechanism. If the history store file exceeds this size, a panic will be triggered. The default value means that the history store file is unbounded and may use as much space as the filesystem will accommodate. The minimum non-zero setting is 100MB.an integer greater than or equal to 0; default 0.
)
io_capacity = (control how many bytes per second are written and read. Exceeding the capacity results in throttling.a set of related configuration options defined as follows.
    chunk_cachenumber of bytes per second available to the chunk cache. The minimum non-zero setting is 1MB.an integer between 0 and 1TB; default 0.
    totalnumber of bytes per second available to all subsystems in total. When set, decisions about what subsystems are throttled, and in what proportion, are made internally. The minimum non-zero setting is 1MB.an integer between 0 and 1TB; default 0.
)
json_outputenable JSON formatted messages on the event handler interface. Options are given as a list, where each option specifies an event handler category e.g. 'error' represents the messages from the WT_EVENT_HANDLER::handle_error method.a list, with values chosen from the following options: "error", "message"; default [].
log = (enable logging. Enabling logging uses three sessions from the configured session_max.a set of related configuration options defined as follows.
    os_cache_dirty_pctmaximum dirty system buffer cache usage, as a percentage of the log's file_max. If non-zero, schedule writes for dirty blocks belonging to the log in the system buffer cache after that percentage of the log has been written into the buffer cache without an intervening file sync.an integer between 0 and 100; default 0.
    preallocpre-allocate log files.a boolean flag; default true.
    prealloc_init_countinitial number of pre-allocated log files.an integer between 1 and 500; default 1.
    removeautomatically remove unneeded log files.a boolean flag; default true.
    zero_fillmanually write zeroes into log files.a boolean flag; default false.
)
lsm_manager = (configure database wide options for LSM tree management. The LSM manager is started automatically the first time an LSM tree is opened. The LSM manager uses a session from the configured session_max.a set of related configuration options defined as follows.
    mergemerge LSM chunks where possible.a boolean flag; default true.
    worker_thread_maxConfigure a set of threads to manage merging LSM trees in the database. Each worker thread uses a session handle from the configured session_max.an integer between 3 and 20; default 4.
)
operation_timeout_msthis option is no longer supported, retained for backward compatibility.an integer greater than or equal to 0; default 0.
operation_tracking = (enable tracking of performance-critical functions. See Track function calls for more information.a set of related configuration options defined as follows.
    enabledenable operation tracking subsystem.a boolean flag; default false.
    paththe name of a directory into which operation tracking files are written. The directory must already exist. If the value is not an absolute path, the path is relative to the database home (see Absolute paths for more information).a string; default ".".
)
shared_cache = (shared cache configuration options. A database should configure either a cache_size or a shared_cache not both. Enabling a shared cache uses a session from the configured session_max. A shared cache can not have absolute values configured for cache eviction settings.a set of related configuration options defined as follows.
    chunkthe granularity that a shared cache is redistributed.an integer between 1MB and 10TB; default 10MB.
     namethe name of a cache that is shared between databases or "none" when no shared cache is configured.a string; default none.
    quotamaximum size of cache this database can be allocated from the shared cache. Defaults to the entire shared cache size.an integer; default 0.
    reserveamount of cache this database is guaranteed to have available from the shared cache. This setting is per database. Defaults to the chunk size.an integer; default 0.
    sizemaximum memory to allocate for the shared cache. Setting this will update the value if one is already set.an integer between 1MB and 10TB; default 500MB.
)
statisticsMaintain database statistics, which may impact performance. Choosing "all" maintains all statistics regardless of cost, "fast" maintains a subset of statistics that are relatively inexpensive, "none" turns off all statistics. The "clear" configuration resets statistics after they are gathered, where appropriate (for example, a cache size statistic is not cleared, while the count of cursor insert operations will be cleared). When "clear" is configured for the database, gathered statistics are reset each time a statistics cursor is used to gather statistics, as well as each time statistics are logged using the statistics_log configuration. See Statistics for more information.a list, with values chosen from the following options: "all", "cache_walk", "fast", "none", "clear", "tree_walk"; default none.
statistics_log = (log any statistics the database is configured to maintain, to a file. See Statistics for more information. Enabling the statistics log server uses a session from the configured session_max.a set of related configuration options defined as follows.
    jsonencode statistics in JSON format.a boolean flag; default false.
    on_closelog statistics on database close.a boolean flag; default false.
    sourcesif non-empty, include statistics for the list of "file:" and "lsm:" data source URIs, if they are open at the time of the statistics logging.a list of strings; default empty.
    timestampa timestamp prepended to each log record. May contain strftime conversion specifications. When json is configured, defaults to "%Y-%m-%dT%H:%M:%S.000Z".a string; default "%b %d %H:%M:%S".
    waitseconds to wait between each write of the log records; setting this value above 0 configures statistics logging.an integer between 0 and 100000; default 0.
)
tiered_storage = (enable tiered storage. Enabling tiered storage may use one session from the configured session_max.a set of related configuration options defined as follows.
    local_retentiontime in seconds to retain data on tiered storage on the local tier for faster read access.an integer between 0 and 10000; default 300.
)
verboseenable messages for various subsystems and operations. Options are given as a list, where each message type can optionally define an associated verbosity level, such as "verbose=[eviction,read:1,rts:0]". Verbosity levels that can be provided include 0 (INFO) and 1 through 5, corresponding to (DEBUG_1) to (DEBUG_5). all is a special case that defines the verbosity level for all categories not explicitly set in the config string.a list, with values chosen from the following options: "all", "api", "backup", "block", "block_cache", "checkpoint", "checkpoint_cleanup", "checkpoint_progress", "chunkcache", "compact", "compact_progress", "configuration", "error_returns", "eviction", "fileops", "generation", "handleops", "history_store", "history_store_activity", "log", "lsm", "lsm_manager", "metadata", "mutex", "out_of_order", "overflow", "prefetch", "read", "reconcile", "recovery", "recovery_progress", "rts", "salvage", "shared_cache", "split", "temporary", "thread_group", "tiered", "timestamp", "transaction", "verify", "version", "write"; default [].
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_extra_diagnostics.c.

◆ rollback_to_stable()

int WT_CONNECTION::rollback_to_stable ( WT_CONNECTION connection,
const char *  config 
)

Rollback tables to an earlier point in time, discarding all updates to checkpoint durable tables that have commit times more recent than the current global stable timestamp.

No updates made to logged tables or updates made without an associated commit timestamp will be discarded. See Miscellaneous timestamp topics.

Applications must resolve all running transactions and close or reset all open cursors before the call, and no other API calls should be made for the duration of the call.

error_check(conn->rollback_to_stable(conn, NULL));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
dryrunperform the checks associated with RTS, but don't modify any data.a boolean flag; default false.
threadsmaximum number of threads WiredTiger will start to help RTS. Each RTS worker thread uses a session from the configured session_max.an integer between 0 and 10; default 4.
Returns
zero on success and a non-zero error code on failure. See Error handling for details. An error should occur only in the case of a system problem, and an application typically will retry WT_CONNECTION::rollback_to_stable on error, or fail outright.

◆ set_file_system()

int WT_CONNECTION::set_file_system ( WT_CONNECTION connection,
WT_FILE_SYSTEM fs,
const char *  config 
)

Configure a custom file system.

This method can only be called from an early loaded extension module. The application must first implement the WT_FILE_SYSTEM interface and then register the implementation with WiredTiger:

/*
* Setup a configuration string that will load our custom file system. Use the special local
* extension to indicate that the entry point is in the same executable. Also enable early load
* for this extension, since WiredTiger needs to be able to find it before doing any file
* operations. Finally, pass in two pieces of configuration information to our initialization
* function as the "config" value.
*/
open_config =
"create,log=(enabled=true),extensions=(local={entry=demo_file_system_create,early_load=true,"
"config={config_string=\"demo-file-system\",config_value=37}})";
/* Open a connection to the database, creating it if necessary. */
if ((ret = wiredtiger_open(home, NULL, open_config, &conn)) != 0) {
fprintf(stderr, "Error connecting to %s: %s\n", home == NULL ? "." : home,
return (EXIT_FAILURE);
}
Parameters
connectionthe connection handle
fsthe populated file system structure
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_file_system.c.

◆ set_timestamp()

int WT_CONNECTION::set_timestamp ( WT_CONNECTION connection,
const char *  config 
)

Set a global transaction timestamp.

error_check(conn->set_timestamp(conn, "durable_timestamp=2a"));
error_check(conn->set_timestamp(conn, "oldest_timestamp=2a"));
error_check(conn->set_timestamp(conn, "stable_timestamp=2a"));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
durable_timestamptemporarily set the system's maximum durable timestamp, bounding the timestamp returned by WT_CONNECTION::query_timestamp with the all_durable configuration. Calls to WT_CONNECTION::query_timestamp will ignore durable timestamps greater than the specified value until a subsequent transaction commit advances the maximum durable timestamp, or rollback-to-stable resets the value. See Managing the global timestamp state.a string; default empty.
oldest_timestampfuture commits and queries will be no earlier than the specified timestamp. Values must be monotonically increasing. The value must not be newer than the current stable timestamp. See Managing the global timestamp state.a string; default empty.
stable_timestampcheckpoints will not include commits that are newer than the specified timestamp in tables configured with "log=(enabled=false)". Values must be monotonically increasing. The value must not be older than the current oldest timestamp. See Managing the global timestamp state.a string; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
WT_EXTENSION_API
Table of WiredTiger extension methods.
Definition: wiredtiger_ext.h:58
WT_CONNECTION::get_home
const char * get_home(WT_CONNECTION *connection)
The home directory of the connection.
WT_SESSION::timestamp_transaction
int timestamp_transaction(WT_SESSION *session, const char *config)
Set a timestamp on a transaction.
wiredtiger_strerror
const char * wiredtiger_strerror(int error)
Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...
WT_DATA_SOURCE
Applications can extend WiredTiger by providing new implementations of the WT_DATA_SOURCE class.
Definition: wiredtiger.in:4420
WT_CONNECTION::rollback_to_stable
int rollback_to_stable(WT_CONNECTION *connection, const char *config)
Rollback tables to an earlier point in time, discarding all updates to checkpoint durable tables that...
WT_COLLATOR
The interface implemented by applications to provide custom ordering of records.
Definition: wiredtiger.in:4218
WT_SESSION::commit_transaction
int commit_transaction(WT_SESSION *session, const char *config)
Commit the current transaction.
WT_CONFIG_ARG
struct WT_CONFIG_ARG WT_CONFIG_ARG
Definition: wiredtiger.in:4204
WT_CONNECTION::get_extension_api
WT_EXTENSION_API * get_extension_api(WT_CONNECTION *wt_conn)
Return a reference to the WiredTiger extension functions.
WT_CONNECTION::add_extractor
int add_extractor(WT_CONNECTION *connection, const char *name, WT_EXTRACTOR *extractor, const char *config)
Add a custom extractor for index keys or column groups.
WT_ENCRYPTOR
The interface implemented by applications to provide custom encryption.
Definition: wiredtiger.in:4558
WT_CONNECTION::open_session
int open_session(WT_CONNECTION *connection, WT_EVENT_HANDLER *event_handler, const char *config, WT_SESSION **sessionp)
Open a session.
WT_CONNECTION::is_new
int is_new(WT_CONNECTION *connection)
Return if opening this handle created the database.
WT_CONNECTION::set_timestamp
int set_timestamp(WT_CONNECTION *connection, const char *config)
Set a global transaction timestamp.
WT_CONNECTION::add_collator
int add_collator(WT_CONNECTION *connection, const char *name, WT_COLLATOR *collator, const char *config)
Add a custom collation function.
wiredtiger_extension_init
int wiredtiger_extension_init(WT_CONNECTION *connection, WT_CONFIG_ARG *config)
Entry point to an extension, called when the extension is loaded.
WT_CONNECTION
A connection to a WiredTiger database.
Definition: wiredtiger.in:2106
WT_CONNECTION::add_encryptor
int add_encryptor(WT_CONNECTION *connection, const char *name, WT_ENCRYPTOR *encryptor, const char *config)
Add an encryption function.
WT_EXTRACTOR
The interface implemented by applications to provide custom extraction of index keys or column group ...
Definition: wiredtiger.in:4716
WT_CONNECTION::configure_method
int configure_method(WT_CONNECTION *connection, const char *method, const char *uri, const char *config, const char *type, const char *check)
Add configuration options for a method.
WT_CONNECTION::add_data_source
int add_data_source(WT_CONNECTION *connection, const char *prefix, WT_DATA_SOURCE *data_source, const char *config)
Add a custom data source.
WT_CONNECTION::add_compressor
int add_compressor(WT_CONNECTION *connection, const char *name, WT_COMPRESSOR *compressor, const char *config)
Add a compression function.
wiredtiger_open
int wiredtiger_open(const char *home, WT_EVENT_HANDLER *event_handler, const char *config, WT_CONNECTION **connectionp)
Open a connection to a database.
WT_COMPRESSOR
The interface implemented by applications to provide custom compression.
Definition: wiredtiger.in:4271
WT_CONNECTION::query_timestamp
int query_timestamp(WT_CONNECTION *connection, char *hex_timestamp, const char *config)
Query the global transaction timestamp state.
WT_CONNECTION::reconfigure
int reconfigure(WT_CONNECTION *connection, const char *config)
Reconfigure a connection handle.
WT_SESSION
All data operations are performed in the context of a WT_SESSION.
Definition: wiredtiger.in:822
WT_CONNECTION::close
int close(WT_CONNECTION *connection, const char *config)
Close a connection.
WT_CONNECTION::load_extension
int load_extension(WT_CONNECTION *connection, const char *path, const char *config)
Load an extension.