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...

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_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_API *	get_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_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, NULL };

ret = conn->add_collator(conn, "my_collator", &my_collator, NULL);

Parameters

connection	the connection handle
name	the name of the collation to be used in calls to WT_SESSION::create
collator	the application-supplied collation handler
config	Configuration 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 */
} NOP_COMPRESSOR;
/*
 * A simple shared library compression example.
 */
int
wiredtiger_extension_init(WT_CONNECTION *connection, WT_CONFIG_ARG *config)
{
        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.
         *
         * This could be simplified if only a single database is opened in the
         * application, we could use a static WT_COMPRESSOR structure, and a
         * static reference to the WT_EXTENSION_API methods, then we don't need
         * to allocate memory when the compressor is initialized or free it when
         * the compressor is terminated.  However, this approach is more general
         * purpose and supports multiple databases per application.
         */
        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

connection	the connection handle
name	the name of the compression function to be used in calls to WT_SESSION::create
compressor	the application-supplied compression handler
config	Configuration 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

connection	the connection handle
prefix	the URI prefix for this data source, e.g., "file:"
data_source	the application-supplied implementation of WT_DATA_SOURCE to manage this data source.
config	Configuration 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.

Note: custom extractors 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_extract};
        ret = conn->add_extractor(conn, "my_extractor", &my_extractor, NULL);

Parameters

connection	the connection handle
name	the name of the extractor to be used in calls to WT_SESSION::create
extractor	the application-supplied extractor
config	Configuration 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

connection	the connection handle
config	Configuration 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.

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.
         */
        ret = conn->configure_method(conn,
            "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,
            "session.open_cursor", "my_data:", "devices", "list", NULL);

Parameters

connection	the connection handle
method	the name of the method
uri	the object type or NULL for all object types
config	the additional configuration's name and default value
type	the additional configuration's type (must be one of `"boolean"\`, `"int"`, `"list"` or `"string"`)
check	the 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_conn the WT_CONNECTION handle

Returns: a reference to a WT_EXTENSION_API structure.

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

connection the 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

connection the 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

connection the connection handle

path the filename of the extension module

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`config`	configuration string passed to the entry point of the extension as its WT_CONFIG_ARG argument.	a string; default empty.
`entry`	the 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`.
`terminate`	an 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

connection the connection handle

errhandler An error handler. If NULL, the connection's error handler is used

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`isolation`	the default isolation level for operations in this session.	a string, chosen from the following options: `"read-uncommitted"`, `"read-committed"`, `"snapshot"`; default `read-committed`.

[out] sessionp the 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

connection the connection handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`cache_size`	maximum heap memory to allocate for the cache. A database should configure either a cache_size or a shared_cache not both.	an integer between 1MB and 10TB; default `100MB`.
`error_prefix`	prefix string for error messages.	a string; default empty.
`eviction_dirty_target`	continue evicting until the cache has less dirty pages than this (as a percentage). Dirty pages will only be evicted if the cache is full enough to trigger eviction.	an integer between 10 and 99; default `80`.
`eviction_target`	continue 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_trigger`	trigger eviction when the cache becomes this full (as a percentage).	an integer between 10 and 99; default `95`.
`shared_cache = (`	shared cache configuration options. A database should configure either a cache_size or a shared_cache not both.	a set of related configuration options defined below.
`enable`	whether the connection is using a shared cache.	a boolean flag; default `false`.
`chunk`	the granularity that a shared cache is redistributed.	an integer between 1MB and 10TB; default `10MB`.
`reserve`	amount 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`.
`name`	name of a cache that is shared between databases.	a string; default `pool`.
`size`	maximum 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`.
`)`
`statistics`	Maintain 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`.
`verbose`	enable 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"`, `"compact"`, `"evict"`, `"evictserver"`, `"fileops"`, `"hazard"`, `"log"`, `"lsm"`, `"mutex"`, `"overflow"`, `"read"`, `"readserver"`, `"reconcile"`, `"recovery"`, `"salvage"`, `"shared_cache"`, `"verify"`, `"version"`, `"write"`; default empty.

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

Public Member Functions

Detailed Description

Member Function Documentation