Version 1.3.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.
 
int reconfigure (WT_CONNECTION *connection, const char *config)
 Reconfigure a connection handle.
 
const char * get_home (WT_CONNECTION *connection)
 The home directory of the connection.
 
int is_new (WT_CONNECTION *connection)
 Return if opening this handle created the database.
 
Session handles
int open_session (WT_CONNECTION *connection, WT_EVENT_HANDLER *errhandler, const char *config, WT_SESSION **sessionp)
 Open a session.
 
Extensions
int load_extension (WT_CONNECTION *connection, const char *path, const char *config)
 Load an extension.
 
int add_data_source (WT_CONNECTION *connection, const char *prefix, WT_DATA_SOURCE *data_source, const char *config)
 Add a custom data source.
 
int add_collator (WT_CONNECTION *connection, const char *name, WT_COLLATOR *collator, const char *config)
 Add a custom collation function.
 
int add_compressor (WT_CONNECTION *connection, const char *name, WT_COMPRESSOR *compressor, const char *config)
 Add a compression function.
 
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.
 

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_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.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 };
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
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:

static WT_COMPRESSOR my_compressor = {
my_compress, my_decompress, my_pre_size };
ret = conn->add_compressor(conn, "my_compress", &my_compressor, NULL);
Parameters
connectionthe connection handle
namethe name of the compression function to be used in calls to WT_SESSION::create
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.

Not yet supported in WiredTiger.

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_drop,
my_open_cursor,
my_rename,
my_truncate
};
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_extractor ( WT_CONNECTION connection,
const char *  name,
WT_EXTRACTOR extractor,
const char *  config 
)

Add a custom extractor for index keys or column groups.

Not yet supported in WiredTiger.

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

static WT_EXTRACTOR my_extractor;
my_extractor.extract = my_extract;
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
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.
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. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_access.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.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);
Parameters
connectionthe connection handle
paththe filename of the extension module
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
entrythe entry point of the extension.a string; default wiredtiger_extension_init.
prefixa prefix for all names registered by this extension (e.g., to make namespaces distinct or during upgrades.a string; default empty.
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
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.
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_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.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
cache_sizemaximum heap memory to allocate for the cache.an integer between 1MB and 10TB; default 100MB.
error_prefixprefix string for error messages.a string; default empty.
eviction_targetcontinue evicting until the cache becomes less full than this (as a percentage). Must be less than eviction_trigger.an integer between 10 and 99; default 80.
eviction_triggertrigger eviction when the cache becomes this full (as a percentage).an integer between 10 and 99; default 95.
verboseenable messages for various events. Options are given as a list, such as "verbose=[evictserver,read]".a list, with values chosen from the following options: "block", "ckpt", "evict", "evictserver", "fileops", "hazard", "lsm", "mutex", "read", "readserver", "reconcile", "salvage", "verify", "write"; default empty.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.