Version 2.8.0
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 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...
 
Async operation handles
int async_flush (WT_CONNECTION *connection)
 Wait for all outstanding operations to complete. More...
 
int async_new_op (WT_CONNECTION *connection, const char *uri, const char *config, WT_ASYNC_CALLBACK *callback, WT_ASYNC_OP **asyncopp)
 Return an async operation handle. More...
 
Session handles
int open_session (WT_CONNECTION *connection, WT_EVENT_HANDLER *errhandler, const char *config, WT_SESSION **sessionp)
 Open a session. 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...
 
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_async.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, nop_encrypt.c, and rotn_encrypt.c.

Member Function Documentation

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 };
ret = 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 Returns for details.
Examples:
ex_extending.c.
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;
(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.compress_raw = NULL;
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 */
return (connection->add_compressor(
connection, "nop", (WT_COMPRESSOR *)nop_compressor, NULL));
}
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 Returns for details.
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_create,
my_compact,
my_drop,
my_open_cursor,
my_rename,
my_salvage,
my_truncate,
my_range_truncate,
my_verify,
my_checkpoint,
my_terminate
};
ret = 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 Returns for details.
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;
(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.terminate = nop_terminate;
nop_encryptor->wt_api = connection->get_extension_api(connection);
/* Load the encryptor */
return (connection->add_encryptor(
connection, "nop", (WT_ENCRYPTOR *)nop_encryptor, NULL));
}
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 Returns for details.
Examples:
ex_encrypt.c, nop_encrypt.c, and rotn_encrypt.c.
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};
ret = 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 Returns for details.
Examples:
ex_extractor.c.
int WT_CONNECTION::async_flush ( WT_CONNECTION connection)

Wait for all outstanding operations to complete.

/* Wait for all outstanding operations to complete. */
ret = conn->async_flush(conn);
Parameters
connectionthe connection handle
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_async.c.
int WT_CONNECTION::async_new_op ( WT_CONNECTION connection,
const char *  uri,
const char *  config,
WT_ASYNC_CALLBACK callback,
WT_ASYNC_OP **  asyncopp 
)

Return an async operation handle.

while ((ret = conn->async_new_op(conn,
"table:async", NULL, &ex_asynckeys.iface, &op)) != 0) {
/*
* If we used up all the handles, pause and retry to
* give the workers a chance to catch up.
*/
fprintf(stderr,
"asynchronous operation handle not available\n");
if (ret == EBUSY)
sleep(1);
else
return (ret);
}
Parameters
connectionthe connection handle
urithe connection handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
appendappend the value as a new record, creating a new record number key; valid only for operations with record number keys.a boolean flag; default false.
overwriteconfigures whether the cursor's insert, update and remove methods check the existing state of the record. If overwrite is false, WT_CURSOR::insert fails with WT_DUPLICATE_KEY if the record exists, WT_CURSOR::update and WT_CURSOR::remove fail with WT_NOTFOUND if the record does not exist.a boolean flag; default true.
rawignore the encodings for the key and value, manage data as if the formats were "u". See Raw mode for details.a boolean flag; default false.
timeoutmaximum amount of time to allow for compact in seconds. The actual amount of time spent in compact may exceed the configured value. A value of zero disables the timeout.an integer; default 1200.
callbackthe operation callback
[out]asyncoppthe new op handle
Returns
zero on success and a non-zero error code on failure. See Error Returns for details. If there are no available handles, EBUSY is returned.
Examples:
ex_async.c.
int WT_CONNECTION::close ( WT_CONNECTION connection,
const char *  config 
)

Close a connection.

Any open sessions will be closed.

ret = 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.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_access.c, ex_async.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.
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.
*/
ret = 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.
*/
ret = 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 Returns for details.
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, nop_encrypt.c, and rotn_encrypt.c.
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
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.
int WT_CONNECTION::load_extension ( WT_CONNECTION connection,
const char *  path,
const char *  config 
)

Load an extension.

ret = conn->load_extension(conn, "my_extension.dll", NULL);
ret = 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.
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 Returns for details.
int WT_CONNECTION::open_session ( WT_CONNECTION connection,
WT_EVENT_HANDLER errhandler,
const char *  config,
WT_SESSION **  sessionp 
)

Open a session.

WT_SESSION *session;
ret = conn->open_session(conn, NULL, NULL, &session);
Parameters
connectionthe connection handle
errhandlerAn error handler. If NULL, the connection's error handler is used. See Error handling using the WT_EVENT_HANDLER for more information.
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
isolationthe default isolation level for operations in this session.a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default read-committed.
[out]sessionpthe new session handle
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_access.c, ex_async.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.
int WT_CONNECTION::reconfigure ( WT_CONNECTION connection,
const char *  config 
)

Reconfigure a connection handle.

ret = conn->reconfigure(conn, "eviction_target=75");
Parameters
connectionthe connection handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
async = (asynchronous operations configuration options.a set of related configuration options defined below.
    enabledenable asynchronous operation.a boolean flag; default false.
    ops_maxmaximum number of expected simultaneous asynchronous operations.an integer between 1 and 4096; default 1024.
    threadsthe number of worker threads to service asynchronous requests. Each worker thread uses a session from the configured session_max.an integer between 1 and 20; default 2.
)
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.
checkpoint = (periodically checkpoint the database. Enabling the checkpoint server uses a session from the configured session_max.a set of related configuration options defined below.
    log_sizewait for this amount of log record bytes to be written to the log between each checkpoint. 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.
    namethe checkpoint name.a string; default "WiredTigerCheckpoint".
    waitseconds to wait between each checkpoint; setting this value above 0 configures periodic checkpoints.an integer between 0 and 100000; default 0.
)
error_prefixprefix string for error messages.a string; default empty.
eviction = (eviction configuration options.a set of related configuration options defined below.
    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 1.
    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_dirty_targetcontinue evicting until the cache has less dirty memory than the value, as a percentage of the total cache size. Dirty pages will only be evicted if the cache is full enough to trigger eviction.an integer between 5 and 99; default 80.
eviction_dirty_triggertrigger eviction when the cache is using this much memory for dirty content, as a percentage of the total cache size. This setting only alters behavior if it is lower than eviction_trigger.an integer between 5 and 99; default 95.
eviction_targetcontinue evicting until the cache has less total memory than the value, as a percentage of the total cache size. Must be less than eviction_trigger.an integer between 10 and 99; default 80.
eviction_triggertrigger eviction when the cache is using this much memory, as a percentage of the total cache size.an integer between 10 and 99; default 95.
file_manager = (control how file handles are managed.a set of related configuration options defined below.
    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.
)
log = (enable logging. Enabling logging uses three sessions from the configured session_max.a set of related configuration options defined below.
    archiveautomatically archive unneeded log files.a boolean flag; default true.
    compressorconfigure a compressor for log records. Permitted values are "none" or custom compression engine name created with WT_CONNECTION::add_compressor. If WiredTiger has builtin support for "snappy", "lz4" or "zlib" compression, these names are also available. See Compressors for more information.a string; default none.
    enabledenable logging subsystem.a boolean flag; default false.
    file_maxthe maximum size of log files.an integer between 100KB and 2GB; default 100MB.
    paththe path to a directory into which the log files are written. If the value is not an absolute path name, the files are created relative to the database home.a string; default empty.
    preallocpre-allocate log files.a boolean flag; default true.
    recoverrun recovery or error if recovery needs to run after an unclean shutdown.a string, chosen from the following options: "error", "on"; default on.
    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 below.
    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.
)
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 set of related configuration options defined below.
    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", "fast", "none", "clear"; 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 below.
    jsonencode statistics in JSON format.a boolean flag; default false.
    on_closelog statistics on database close.a boolean flag; default false.
    paththe pathname to a file into which the log records are written, may contain ISO C standard strftime conversion specifications. If the value is not an absolute path name, the file is created relative to the database home.a string; default "WiredTigerStat.%d.%H".
    sourcesif non-empty, include statistics for the list of data source URIs, if they are open at the time of the statistics logging. The list may include URIs matching a single data source ("table:mytable"), or a URI matching all data sources of a particular type ("table:").a list of strings; default empty.
    timestampa timestamp prepended to each log record, may contain strftime conversion specifications, when json is configured, defaults to "%FT%Y.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.
)
verboseenable messages for various events. Only available if WiredTiger is configured with –enable-verbose. Options are given as a list, such as "verbose=[evictserver,read]".a list, with values chosen from the following options: "api", "block", "checkpoint", "compact", "evict", "evictserver", "fileops", "log", "lsm", "lsm_manager", "metadata", "mutex", "overflow", "read", "rebalance", "reconcile", "recovery", "salvage", "shared_cache", "split", "temporary", "transaction", "verify", "version", "write"; default empty.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.