Python wrapper around C WT_SESSION. More...

Inheritance diagram for wiredtiger.Session:

Public Member Functions
def	__init__

def	close
	close(self, config) -> int

def	reconfigure
	reconfigure(self, config) -> int

def	open_cursor
	open_cursor(self, uri, to_dup, config) -> int

def	create
	create(self, name, config) -> int

def	drop
	drop(self, name, config) -> int

def	rename
	rename(self, oldname, newname, config) -> int

def	salvage
	salvage(self, name, config) -> int

def	truncate
	truncate(self, name, start, stop, config) -> int

def	upgrade
	upgrade(self, name, config) -> int

def	verify
	verify(self, name, config) -> int

def	begin_transaction
	begin_transaction(self, config) -> int

def	commit_transaction
	commit_transaction(self, config) -> int

def	rollback_transaction
	rollback_transaction(self, config) -> int

def	checkpoint
	checkpoint(self, config) -> int

def	dumpfile
	dumpfile(self, name, config) -> int

def	msg_printf
	msg_printf(self, fmt) -> int

Public Attributes
	this

Detailed Description

Python wrapper around C WT_SESSION.

Member Function Documentation

def wiredtiger.Session.begin_transaction	(	self,
		args
	)

begin_transaction(self, config) -> int

Start a transaction in this session. The transaction remains active until ended by WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction. Operations performed on cursors capable of supporting transactional operations that are already open in this session, or which are opened before the transaction ends, will operate in the context of the transaction.All open cursors are reset.WT_SESSION::transaction_begin will fail if a transaction is already in progress in the session.

        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);
        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * The begin_transaction call resets all open cursors.
         */
        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * The commit_transaction call resets all open cursors.
                 * If commit_transaction fails, the transaction was rolled-back.
                 */
                break;
        case WT_DEADLOCK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all open cursors. */
                break;
        }
        /* Cursors remain open and may be used for multiple transactions. */

Parameters

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`isolation`	the isolation level for this transaction; defaults to the session's isolation level.	a string, chosen from the following options: `"read-uncommitted"`, `"read-committed"`, `"snapshot"`; default empty.
`name`	name of the transaction for tracing and debugging.	a string; default empty.
`priority`	priority of the transaction for resolving conflicts. Transactions with higher values are less likely to abort.	an integer between -100 and 100; default `0`.
`sync`	how to sync log records when the transaction commits.	a string, chosen from the following options: `"full"`, `"flush"`, `"write"`, `"none"`; default `full`.

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

def wiredtiger.Session.checkpoint	(	self,
		args
	)

checkpoint(self, config) -> int

Write a transactionally consistent snapshot of a database or set of objects. The checkpoint includes all transactions committed before the checkpoint starts. Additionally, checkpoints may optionally be discarded.

        /* Checkpoint the database. */
        ret = session->checkpoint(session, NULL);
        /* Checkpoint of the database, creating a named snapshot. */
        ret = session->checkpoint(session, "name=June01");
        /*
         * Checkpoint a list of objects.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->
            checkpoint(session, "target=(\"table:table1\",\"table:table2\")");
        /*
         * Checkpoint a list of objects, creating a named snapshot.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->
            checkpoint(session, "target=(\"table:mytable\"),name=midnight");
        /* Checkpoint the database, discarding all previous snapshots. */
        ret = session->checkpoint(session, "drop=(from=all)");
        /* Checkpoint the database, discarding the "midnight" snapshot. */
        ret = session->checkpoint(session, "drop=(midnight)");
        /*
         * Checkpoint the database, discarding all snapshots after and
         * including "noon".
         */
        ret = session->checkpoint(session, "drop=(from=noon)");
        /*
         * Checkpoint the database, discarding all snapshots before and
         * including "midnight".
         */
        ret = session->checkpoint(session, "drop=(to=midnight)");
        /*
         * Create a checkpoint of a table, creating the "July01" snapshot and
         * discarding the "May01" and "June01" snapshots.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->checkpoint(session,
            "target=(\"table:mytable\"),name=July01,drop=(May01,June01)");

Parameters

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`drop`	specify a list of checkpoints to drop. The list may additionally contain one of the following keys: `"from=all"` to drop all checkpoints, `"from=<checkpoint>"` to drop all checkpoints after and including the named checkpoint, or `"to=<checkpoint>"` to drop all checkpoints before and including the named checkpoint. Checkpoints cannot be dropped while a hot backup is in progress or if open in a cursor.	a list of strings; default empty.
`name`	if non-empty, specify a name for the checkpoint.	a string; default empty.
`target`	if non-empty, checkpoint the list of objects.	a list of strings; default empty.

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

def wiredtiger.Session.close	(	self,
		args
	)

close(self, config) -> int

Close the session handle. 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.

ret = session->close(session, NULL);

Parameters

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

def wiredtiger.Session.commit_transaction	(	self,
		args
	)

commit_transaction(self, config) -> int

Commit the current transaction. A transaction must be in progress when this method is called.All open cursors are reset.If WT_SESSION::commit_transaction returns an error, the transaction was rolled-back, not committed.

        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);
        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * The begin_transaction call resets all open cursors.
         */
        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * The commit_transaction call resets all open cursors.
                 * If commit_transaction fails, the transaction was rolled-back.
                 */
                break;
        case WT_DEADLOCK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all open cursors. */
                break;
        }
        /* Cursors remain open and may be used for multiple transactions. */

Parameters

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

def wiredtiger.Session.create	(	self,
		args
	)

create(self, name, config) -> int

Create a table, column group, index or file.

ret = session->create(session,

"table:mytable", "key_format=S,value_format=S");

Parameters

session the session handle

name the URI of the object to create, such as "table:stock"

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`allocation_size`	the file unit allocation size, in bytes, must a power-of-two; smaller values decrease the file space required by overflow items, and the default value of 512B is a good choice absent requirements from the operating system or storage device.	an integer between 512B and 128MB; default `512B`.
`block_compressor`	configure a compressor for file blocks. Permitted values are empty (off) or `"bzip2"`, `"snappy"` or custom compression engine `"name"` created with WT_CONNECTION::add_compressor. See Compressors for more information.	a string; default empty.
`cache_resident`	do not ever evict the object's pages; see Cache resident objects for more information.	a boolean flag; default `false`.
`checksum`	configure file block checksums; if false, the block manager is free to not write or check block checksums. This can increase performance in applications where compression provides checksum functionality or read-only applications where blocks require no verification.	a boolean flag; default `true`.
`colgroups`	comma-separated list of names of column groups. Each column group is stored separately, keyed by the primary key of the table. If no column groups are specified, all columns are stored together in a single file. All value columns in the table must appear in at least one column group. Each column group must be created with a separate call to WT_SESSION::create.	a list of strings; default empty.
`collator`	configure custom collation for keys. Value must be a collator name created with WT_CONNECTION::add_collator.	a string; default empty.
`columns`	list of the column names. Comma-separated list of the form `(column[,...])`. For tables, the number of entries must match the total number of values in `key_format` and `value_format`. For colgroups and indices, all column names must appear in the list of columns for the table.	a list of strings; default empty.
`dictionary`	the number of entries maintained in the Btree row-store leaf page value dictionary; see File formats and compression for more information.	an integer greater than or equal to 0; default `0`.
`exclusive`	fail if the object exists. When false (the default), if the object exists, check that its settings match the specified configuration.	a boolean flag; default `false`.
`filename`	override the default filename derived from the object name.	a string; default empty.
`huffman_key`	configure Huffman encoding for keys. Permitted values are empty (off), `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information.	a string; default empty.
`huffman_value`	configure Huffman encoding for values. Permitted values are empty (off), `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information.	a string; default empty.
`internal_item_max`	the maximum key size stored on internal nodes, in bytes. If zero, a maximum is calculated to permit at least 8 keys per internal page.	an integer greater than or equal to 0; default `0`.
`internal_key_truncate`	configure internal key truncation, discarding unnecessary trailing bytes on internal keys (ignored for custom collators).	a boolean flag; default `true`.
`internal_page_max`	the maximum page size for internal nodes, in bytes; the size must be a multiple of the allocation size and is significant for applications wanting to avoid excessive L2 cache misses while searching the tree.	an integer between 512B and 512MB; default `2KB`.
`key_format`	the format of the data packed into key items. See Format types for details. By default, the key_format is `'u'` and applications use WT_ITEM structures to manipulate raw byte arrays. By default, records are stored in row-store files: keys of type `'r'` are record numbers and records referenced by record number are stored in column-store files.	a format string; default `u`.
`key_gap`	the maximum gap between instantiated keys in a Btree leaf page, constraining the number of keys processed to instantiate a random Btree leaf page key.	an integer greater than or equal to 0; default `10`.
`leaf_item_max`	the maximum key or value size stored on leaf nodes, in bytes. If zero, a size is calculated to permit at least 8 items (values or row store keys) per leaf page.	an integer greater than or equal to 0; default `0`.
`leaf_page_max`	the maximum page size for leaf nodes, in bytes; the size must be a multiple of the allocation size, and is significant for applications wanting to maximize sequential data transfer from a storage device.	an integer between 512B and 512MB; default `1MB`.
`lsm_bloom_bit_count`	the number of bits used per item for LSM bloom filters..	an integer between 2 and 1000; default `8`.
`lsm_bloom_hash_count`	the number of hash values per item used for LSM bloom filters..	an integer between 2 and 100; default `4`.
`lsm_chunk_size`	the maximum size of the in-memory chunk of an LSM tree.	an integer between 512K and 500MB; default `2MB`.
`prefix_compression`	configure row-store format key prefix compression.	a boolean flag; default `true`.
`split_pct`	the Btree page split size as a percentage of the maximum Btree page size, that is, when a Btree page is split, it will be split into smaller pages, where each page is the specified percentage of the maximum Btree page size.	an integer between 25 and 100; default `75`.
`type`	the file type.	a string, chosen from the following options: `"btree"`; default `btree`.
`value_format`	the format of the data packed into value items. See Format types for details. By default, the value_format is `'u'` and applications use a WT_ITEM structure to manipulate raw byte arrays. Value items of type 't' are bitfields, and when configured with record number type keys, will be stored using a fixed-length store.	a format string; default `u`.

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

def wiredtiger.Session.drop	(	self,
		args
	)

drop(self, name, config) -> int

Drop (delete) an object.

ret = session->drop(session, "table:mytable", NULL);

Parameters

session the session handle

name the URI of the object to drop, such as "table:stock"

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`force`	return success if the object does not exist.	a boolean flag; default `false`.

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

def wiredtiger.Session.dumpfile	(	self,
		args
	)

dumpfile(self, name, config) -> int

Dump a physical file in debugging mode. The specified file is displayed in a non-portable debugging mode to the application's standard output.

ret = session->dumpfile(session, "file:myfile", NULL);

Parameters

session	the session handle
name	the URI of the file to dump
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.

def wiredtiger.Session.msg_printf	(	self,
		args
	)

msg_printf(self, fmt) -> int

Send a string to the message handler for debugging.

ret = session->msg_printf(

session, "process ID %" PRIuMAX, (uintmax_t)getpid());

Parameters

session	the session handle
fmt	a printf-like format specification

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

def wiredtiger.Session.open_cursor	(	self,
		args
	)

open_cursor(self, uri, to_dup, config) -> int

Open a new cursor on a data source or duplicate an existing cursor.

ret = session->open_cursor(

session, "table:mytable", NULL, NULL, &cursor);

An existing cursor can be duplicated by passing it as the to_dup parameter and setting the uri parameter to NULL:

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
        cursor->set_key(cursor, key);
        ret = cursor->search(cursor);
        /* Duplicate the cursor. */
        ret = session->open_cursor(session, NULL, cursor, NULL, &duplicate);

Cursors being duplicated must have a key set, and successfully duplicated cursors are positioned at the same place in the data source as the original.To reconfigure a cursor, duplicate it with a new configuration value:

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
        cursor->set_key(cursor, key);
        /* Reconfigure the cursor to overwrite the record. */
        ret = session->open_cursor(
            session, NULL, cursor, "overwrite=true", &overwrite_cursor);
        ret = cursor->close(cursor);
        overwrite_cursor->set_value(overwrite_cursor, value);
        ret = overwrite_cursor->insert(cursor);

Cursor handles should be discarded by calling WT_CURSOR::close.Cursors capable of supporting transactional operations operate in the context of the current transaction, if any. Ending a transaction implicitly resets all open cursors.Cursors are relatively light-weight objects but may hold references to heavier-weight objects; applications should re-use cursors when possible, but instantiating new cursors is not so expensive that applications need to cache cursors at all cost.

Parameters

session the session handle

uri

the data source on which the cursor operates; cursors are usually opened on tables, however, cursors can be opened on any data source, regardless of whether it is ultimately stored in a table. Some cursor types may have limited functionality (for example, they may be read-only or not support transactional updates). See Data Sources for more information.
The following are the builtin cursor types:

URI	Type	Key/Value types
`backup:`	hot backup cursor	key=`string`, see Hot backup for details
`colgroup:<tablename>.<columnset>`	column group cursor	table key, column group value(s)
`table:<tablename>`	table cursor	table key, table value(s)
`file:<filename>`	file cursor	file key, file value(s)
`index:<tablename>.<indexname>`	index cursor	key=index key, value=table value(s)
`statistics:[file:<filename>]`	database or file statistics cursor	key=`int id`, value=(`string description, string value, uint64_t value`), see Statistics Data for details

to_dup a cursor to duplicate

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`append`	append the value as a new record, creating a new record number key; valid only for cursors with record number keys.	a boolean flag; default `false`.
`bulk`	configure the cursor for bulk loads; bulk-load is a fast load path for empty objects and only empty objects may be bulk-loaded. Cursors configured for bulk load only support the WT_CURSOR::insert and WT_CURSOR::close methods.	a boolean flag; default `false`.
`checkpoint`	the name of a checkpoint to open; the reserved checkpoint name "WiredTigerCheckpoint" opens a cursor on the most recent internal checkpoint taken for the object.	a string; default empty.
`dump`	configure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "print" selects a format where only non-printing characters are hexadecimal encoded. The cursor dump format is compatible with the wt dump and wt load commands.	a string, chosen from the following options: `"hex"`, `"print"`; default empty.
`next_random`	configure the cursor to return a pseudo-random record from the object; valid only for row-store cursors. Cursors configured with next_random only support the WT_CURSOR::next and WT_CURSOR::close methods. See Cursor random for details.	a boolean flag; default `false`.
`overwrite`	change the behavior of the cursor's insert method to overwrite previously existing values.	a boolean flag; default `false`.
`raw`	ignore 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`.
`statistics`	configure the cursor for statistics.	a boolean flag; default `false`.
`statistics_clear`	reset statistics counters when the cursor is closed; valid only for statistics cursors.	a boolean flag; default `false`.
`target`	if non-empty, backup the list of objects; valid only for a backup data source.	a list of strings; default empty.

cursorp a pointer to the newly opened cursor

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

def wiredtiger.Session.reconfigure	(	self,
		args
	)

reconfigure(self, config) -> int

Reconfigure a session handle.

ret = session->reconfigure(session, "isolation=snapshot");

WT_SESSION::reconfigure will fail if a transaction is in progress in the session. All open cursors are reset.

Parameters

session the session handle

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

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

def wiredtiger.Session.rename	(	self,
		args
	)

rename(self, oldname, newname, config) -> int

Rename an object.

ret = session->rename(session, "table:old", "table:new", NULL);

Parameters

session	the session handle
oldname	the current URI of the object, such as `"table:old"`
newname	the new name of the object, such as `"table:new"`
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.

def wiredtiger.Session.rollback_transaction	(	self,
		args
	)

rollback_transaction(self, config) -> int

Roll back the current transaction. A transaction must be in progress when this method is called.All open cursors are reset.

        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);
        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * The begin_transaction call resets all open cursors.
         */
        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * The commit_transaction call resets all open cursors.
                 * If commit_transaction fails, the transaction was rolled-back.
                 */
                break;
        case WT_DEADLOCK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all open cursors. */
                break;
        }
        /* Cursors remain open and may be used for multiple transactions. */

Parameters

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

def wiredtiger.Session.salvage	(	self,
		args
	)

salvage(self, name, config) -> int

Salvage a file or table. Salvage rebuilds the file, or files of which a table is comprised, discarding any corrupted file blocks.Previously deleted records may re-appear, and inserted records may disappear, when salvage is done, so salvage should not be run unless it is known to be necessary. Normally, salvage should be called after a file or table has been corrupted, as reported by the WT_SESSION::verify method.Files are rebuilt in place, the salvage method overwrites the existing files.

ret = session->salvage(session, "table:mytable", NULL);

Parameters

session the session handle

name the URI of the file or table to salvage

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`force`	force salvage even of files that do not appear to be WiredTiger files.	a boolean flag; default `false`.

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

def wiredtiger.Session.truncate	(	self,
		args
	)

truncate(self, name, start, stop, config) -> int

Truncate a file, table or cursor range. Truncate a file or table.

ret = session->truncate(session, "table:mytable", NULL, NULL, NULL);

Truncate a cursor range. When truncating based on a cursor position, it is not required the cursor reference a record in the object, only that the key be set. This allows applications to discard portions of the object name space without knowing exactly what records the object contains.

        WT_CURSOR *start, *stop;
        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &start);
        start->set_key(start, "June01");
        ret = start->search(start);
        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &stop);
        stop->set_key(stop, "June30");
        ret = stop->search(stop);
        ret = session->truncate(session, NULL, start, stop, NULL);

Parameters

session	the session handle
name	the URI of the file or table to truncate
start	optional cursor marking the first record discarded; if `NULL`, the truncate starts from the beginning of the object
stop	optional cursor marking the last record discarded; if `NULL`, the truncate continues to the end of the object
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.

def wiredtiger.Session.upgrade	(	self,
		args
	)

upgrade(self, name, config) -> int

Upgrade a file or table. Upgrade upgrades a file or table, if upgrade is required.

ret = session->upgrade(session, "table:mytable", NULL);

Parameters

session	the session handle
name	the URI of the file or table to upgrade
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.

def wiredtiger.Session.verify	(	self,
		args
	)

verify(self, name, config) -> int

Verify a file or table. Verify reports if a file, or the files of which a table is comprised, have been corrupted. The WT_SESSION::salvage method can be used to repair a corrupted file,

ret = session->verify(session, "table:mytable", NULL);

Parameters

session	the session handle
name	the URI of the file or table to verify
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.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation