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

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:

        static WT_COMPRESSOR my_compressor = {
            my_compress, NULL, my_decompress, my_pre_size };
        ret = conn->add_compressor(conn, "my_compress", &my_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.

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

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.

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

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.

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);

Parameters

connection the connection handle

path the filename of the extension module

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`entry`	the entry point of the extension.	a string; default `wiredtiger_extension_init`.
`prefix`	a 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

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

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.
`chunk`	the granularity that a shared cache is redistributed.	an integer between 1MB and 10TB; default `10MB`.
`min`	minimum amount of cache a database in a shared cache can have.	an integer between 10MB and 10TB; default `50MB`.
`name`	name of a cache that is shared between databases.	a string; default empty.
`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`.
`)`
`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"`, `"shared_cache"`, `"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.

Public Member Functions

Detailed Description

Member Function Documentation