WiredTiger: com.wiredtiger.db.Session Class Reference

| Version 3.1.0

Fork me on GitHub Join my user group
List of all members | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes
com.wiredtiger.db.Session Class Reference
WiredTiger Java API

All data operations are performed in the context of a WT_SESSION. More...

## Public Member Functions
synchronized void | delete ()
Connection | getConnection ()
int | close (String config) throws com.wiredtiger.db.WiredTigerException
| Close the session handle. More...
int | reconfigure (String config) throws com.wiredtiger.db.WiredTigerException
| Reconfigure a session handle. More...
String | strerror (int error) throws com.wiredtiger.db.WiredTigerException
int | alter (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Alter a table. More...
int | create (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Create a table, column group, index or file. More...
int | compact (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Compact a live row- or column-store btree or LSM tree. More...
int | drop (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Drop (delete) an object. More...
int | join (Cursor join_cursor, Cursor ref_cursor, String config) throws com.wiredtiger.db.WiredTigerException
| Join a join cursor with a reference cursor. More...
int | log_flush (String config) throws com.wiredtiger.db.WiredTigerException
| Flush the log. More...
int | log_printf (String format) throws com.wiredtiger.db.WiredTigerException
| Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called). More...
int | rebalance (String uri, String config) throws com.wiredtiger.db.WiredTigerException
| Rebalance a table or file, see Rebalance. More...
int | rename (String uri, String newuri, String config) throws com.wiredtiger.db.WiredTigerException
| Rename an object. More...
int | reset () throws com.wiredtiger.db.WiredTigerException
| Reset the session handle. More...
int | salvage (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Salvage a table or file. More...
int | truncate (String name, Cursor start, Cursor stop, String config) throws com.wiredtiger.db.WiredTigerException
| Truncate a file, table or cursor range. More...
int | upgrade (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Upgrade a table or file. More...
int | verify (String name, String config) throws com.wiredtiger.db.WiredTigerException
| Verify a table or file. More...
int | begin_transaction (String config) throws com.wiredtiger.db.WiredTigerException
| Start a transaction in this session. More...
int | commit_transaction (String config) throws com.wiredtiger.db.WiredTigerException
| Commit the current transaction. More...
int | prepare_transaction (String config) throws com.wiredtiger.db.WiredTigerException
| Prepare the current transaction. More...
int | rollback_transaction (String config) throws com.wiredtiger.db.WiredTigerException
| Roll back the current transaction. More...
int | timestamp_transaction (String config) throws com.wiredtiger.db.WiredTigerException
| Set a timestamp on a transaction. More...
int | checkpoint (String config) throws com.wiredtiger.db.WiredTigerException
| Write a transactionally consistent snapshot of a database or set of objects. More...
int | snapshot (String config) throws com.wiredtiger.db.WiredTigerException
| Manage named snapshot transactions. More...
int | transaction_sync (String config) throws com.wiredtiger.db.WiredTigerException
| Wait for a transaction to become synchronized. More...
int | breakpoint () throws com.wiredtiger.db.WiredTigerException
Cursor | open_cursor (String uri, Cursor to_dup, String config) throws com.wiredtiger.db.WiredTigerException
| Open a new cursor on a data source or duplicate an existing cursor. More...
int | transaction_pinned_range () throws com.wiredtiger.db.WiredTigerException
| Return the transaction ID range pinned by the session handle. More...

## Protected Member Functions
| Session (long cPtr, boolean cMemoryOwn)
int | _java_init (Object jsess)

## Static Protected Member Functions
static long | getCPtr (Session obj)

## Protected Attributes
boolean | swigCMemOwn

## Detailed Description

All data operations are performed in the context of a WT_SESSION.

This encapsulates the thread and transactional context of the operation.

Thread safety: A WT_SESSION handle is not usually shared between threads, see Multithreading for more information.

## Member Function Documentation

## ◆ alter()

int com.wiredtiger.db.Session.alter | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Alter a table.

This will allow modification of some table settings after creation.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

error_check(session->alter(session,
"table:mytable", "access_pattern_hint=random"));

Parameters

  session | the session handle
  name | the URI of the object to alter, such as `"table:stock"`
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `access_pattern_hint` | It is recommended that workloads that consist primarily of updates and/or point queries specify `random`. Workloads that do many cursor scans through large ranges of data specify `sequential` and other workloads specify `none`. The option leads to an advisory call to an appropriate operating system API where available. | a string, chosen from the following options: `"none"`, `"random"`, `"sequential"`; default `none`.
  `app_metadata` | application-owned metadata for this object. | a string; default empty.
  `cache_resident` | do not ever evict the object's pages from cache. Not compatible with LSM tables; see Cache resident objects for more information. | a boolean flag; default `false`.
  `log = (` | the transaction log configuration for this object. Only valid if log is enabled in wiredtiger_open. | a set of related configuration options defined below.
  `enabled` | if false, this object has checkpoint-level durability. | a boolean flag; default `true`.
  `)` |  |

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

## ◆ begin_transaction()

int com.wiredtiger.db.Session.begin_transaction | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

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.

This method must not be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* Opening cursors before the transaction begins allows applications to
* cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all 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
  --- | --- | ---
  `ignore_prepare` | whether to ignore the updates by other prepared transactions as part of read operations of this transaction. | a boolean flag; default `false`.
  `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`.
  `read_timestamp` | read using the specified timestamp. The supplied value must not be older than the current oldest timestamp. See Application-specified Transaction Timestamps. | a string; default empty.
  `round_to_oldest` | if read timestamp is earlier than oldest timestamp, read timestamp will be rounded to oldest timestamp. | a boolean flag; default `false`.
  `snapshot` | use a named, in-memory snapshot, see Named Snapshots. | a string; default empty.
  `sync` | whether to sync log records when the transaction commits, inherited from wiredtiger_open `transaction_sync`. | a boolean flag; default empty.

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

## ◆ breakpoint()

int com.wiredtiger.db.Session.breakpoint | ( |  | ) | throws com.wiredtiger.db.WiredTigerException

## ◆ checkpoint()

int com.wiredtiger.db.Session.checkpoint | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Write a transactionally consistent snapshot of a database or set of objects.

In the absence of transaction timestamps, the checkpoint includes all transactions committed before the checkpoint starts.

When timestamps are in use and a `stable_timestamp` has been set via WT_CONNECTION::set_timestamp and the checkpoint runs with `use_timestamp=true` (the default), updates committed with a timestamp larger than the `stable_timestamp` will not be included in the checkpoint for tables configured with `log=`(enabled=false). For tables with logging enabled, all committed changes will be included in the checkpoint (since recovery would roll them forward anyway).

Additionally, existing named checkpoints may optionally be discarded.

This method must not be called on a session with an active transaction.

/* Checkpoint the database. */
error_check(session->checkpoint(session, NULL));
/* Checkpoint of the database, creating a named snapshot. */
error_check(session->checkpoint(session, "name=June01"));
/*
* Checkpoint a list of objects.
* JSON parsing requires quoting the list of target URIs.
*/
error_check(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.
*/
error_check(session->checkpoint(
session, "target=(\"table:mytable\"),name=midnight"));
/* Checkpoint the database, discarding all previous snapshots. */
error_check(session->checkpoint(session, "drop=(from=all)"));
/* Checkpoint the database, discarding the "midnight" snapshot. */
error_check(session->checkpoint(session, "drop=(midnight)"));
/*
* Checkpoint the database, discarding all snapshots after and
* including "noon".
*/
error_check(session->checkpoint(session, "drop=(from=noon)"));
/*
* Checkpoint the database, discarding all snapshots before and
* including "midnight".
*/
error_check(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.
*/
error_check(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.
  `force` | by default, checkpoints may be skipped if the underlying object has not been modified, this option forces the checkpoint. | a boolean flag; default `false`.
  `name` | if set, specify a name for the checkpoint (note that checkpoints including LSM trees may not be named). | a string; default empty.
  `target` | if non-empty, checkpoint the list of objects. | a list of strings; default empty.
  `use_timestamp` | by default, create the checkpoint as of the last stable timestamp if timestamps are in use, or all current updates if there is no stable timestamp set. If false, this option generates a checkpoint with all updates including those later than the timestamp. | a boolean flag; default `true`.

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

## ◆ close()

int com.wiredtiger.db.Session.close | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

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.

error_check(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 handling for details.

## ◆ commit_transaction()

int com.wiredtiger.db.Session.commit_transaction | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Commit the current transaction.

A transaction must be in progress when this method is called.

If WT_SESSION::commit_transaction returns an error, the transaction was rolled back, not committed.

This method must be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* Opening cursors before the transaction begins allows applications to
* cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all 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
  --- | --- | ---
  `commit_timestamp` | set the commit timestamp for the current transaction. The supplied value must not be older than the first commit timestamp set for the current transaction. The value must also not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps. | a string; default empty.
  `sync` | override whether to sync log records when the transaction commits, inherited from wiredtiger_open `transaction_sync`. The `background` setting initiates a background synchronization intended to be used with a later call to WT_SESSION::transaction_sync. The `off` setting does not wait for record to be written or synchronized. The `on` setting forces log records to be written to the storage device. | a string, chosen from the following options: `"background"`, `"off"`, `"on"`; default empty.

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

## ◆ compact()

int com.wiredtiger.db.Session.compact | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Compact a live row- or column-store btree or LSM tree.

error_check(session->compact(session, "table:mytable", NULL));

Parameters

  session | the session handle
  name | the URI of the object to compact, such as `"table:stock"`
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `timeout` | maximum 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`.

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

## ◆ create()

int com.wiredtiger.db.Session.create | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Create a table, column group, index or file.

error_check(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"`. For a description of URI formats see Data Sources.
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `access_pattern_hint` | It is recommended that workloads that consist primarily of updates and/or point queries specify `random`. Workloads that do many cursor scans through large ranges of data specify `sequential` and other workloads specify `none`. The option leads to an advisory call to an appropriate operating system API where available. | a string, chosen from the following options: `"none"`, `"random"`, `"sequential"`; default `none`.
  `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 4KB is a good choice absent requirements from the operating system or storage device. | an integer between 512B and 128MB; default `4KB`.
  `app_metadata` | application-owned metadata for this object. | a string; default empty.
  `block_allocation` | configure block allocation. Permitted values are `"first"` or `"best"`; the `"first"` configuration uses a first-available algorithm during block allocation, the `"best"` configuration uses a best-fit algorithm. | a string, chosen from the following options: `"first"`, `"best"`; default `best`.
  `block_compressor` | configure a compressor for file blocks. Permitted values are `"none"` or custom compression engine name created with WT_CONNECTION::add_compressor. If WiredTiger has builtin support for `"lz4"`, `"snappy"`, `"zlib"` or `"zstd"` compression, these names are also available. See Compressors for more information. | a string; default `none`.
  `cache_resident` | do not ever evict the object's pages from cache. Not compatible with LSM tables; see Cache resident objects for more information. | a boolean flag; default `false`.
  `checksum` | configure block checksums; permitted values are `on` (checksum all blocks), `off` (checksum no blocks) and `uncompresssed` (checksum only blocks which are not compressed for any reason). The `uncompressed` setting is for applications which can rely on decompression to fail if a block has been corrupted. | a string, chosen from the following options: `"on"`, `"off"`, `"uncompressed"`; default `uncompressed`.
  `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. Permitted values are `"none"` or a custom collator name created with WT_CONNECTION::add_collator. | a string; default `none`.
  `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 maximum number of unique values remembered 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`.
  `encryption = (` | configure an encryptor for file blocks. When a table is created, its encryptor is not implicitly used for any related indices or column groups. | a set of related configuration options defined below.
  `keyid` | An identifier that identifies a unique instance of the encryptor. It is stored in clear text, and thus is available when the wiredtiger database is reopened. On the first use of a (name, keyid) combination, the WT_ENCRYPTOR::customize function is called with the keyid as an argument. | a string; default empty.
  `name` | Permitted values are `"none"` or custom encryption engine name created with WT_CONNECTION::add_encryptor. See Encryptors for more information. | a string; default `none`.
  `)` |  |
  `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`.
  `extractor` | configure custom extractor for indices. Permitted values are `"none"` or an extractor name created with WT_CONNECTION::add_extractor. | a string; default `none`.
  `format` | the file format. | a string, chosen from the following options: `"btree"`; default `btree`.
  `huffman_key` | configure Huffman encoding for keys. Permitted values are `"none"`, `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information. | a string; default `none`.
  `huffman_value` | configure Huffman encoding for values. Permitted values are `"none"`, `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information. | a string; default `none`.
  `ignore_in_memory_cache_size` | allow update and insert operations to proceed even if the cache is already at capacity. Only valid in conjunction with in-memory databases. Should be used with caution - this configuration allows WiredTiger to consume memory over the configured cache limit. | a boolean flag; default `false`.
  `immutable` | configure the index to be immutable - that is an index is not changed by any update to a record in the table. | a boolean flag; default `false`.
  `internal_key_max` | the largest key stored in an internal node, in bytes. If set, keys larger than the specified size are stored as overflow items (which may require additional I/O to access). The default and the maximum allowed value are both one-tenth the size of a newly split 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. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done. | an integer between 512B and 512MB; default `4KB`.
  `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`.
  `leaf_key_max` | the largest key stored in a leaf node, in bytes. If set, keys larger than the specified size are stored as overflow items (which may require additional I/O to access). The default value is one-tenth the size of a newly split 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. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done. | an integer between 512B and 512MB; default `32KB`.
  `leaf_value_max` | the largest value stored in a leaf node, in bytes. If set, values larger than the specified size are stored as overflow items (which may require additional I/O to access). If the size is larger than the maximum leaf page size, the page size is temporarily ignored when large values are written. The default is one-half the size of a newly split leaf page. | an integer greater than or equal to 0; default `0`.
  `log = (` | the transaction log configuration for this object. Only valid if log is enabled in wiredtiger_open. | a set of related configuration options defined below.
  `enabled` | if false, this object has checkpoint-level durability. | a boolean flag; default `true`.
  `)` |  |
  `lsm = (` | options only relevant for LSM data sources. | a set of related configuration options defined below.
  `auto_throttle` | Throttle inserts into LSM trees if flushing to disk isn't keeping up. | a boolean flag; default `true`.
  `bloom` | create bloom filters on LSM tree chunks as they are merged. | a boolean flag; default `true`.
  `bloom_bit_count` | the number of bits used per item for LSM bloom filters. | an integer between 2 and 1000; default `16`.
  `bloom_config` | config string used when creating Bloom filter files, passed to WT_SESSION::create. | a string; default empty.
  `bloom_hash_count` | the number of hash values per item used for LSM bloom filters. | an integer between 2 and 100; default `8`.
  `bloom_oldest` | create a bloom filter on the oldest LSM tree chunk. Only supported if bloom filters are enabled. | a boolean flag; default `false`.
  `chunk_count_limit` | the maximum number of chunks to allow in an LSM tree. This option automatically times out old data. As new chunks are added old chunks will be removed. Enabling this option disables LSM background merges. | an integer; default `0`.
  `chunk_max` | the maximum size a single chunk can be. Chunks larger than this size are not considered for further merges. This is a soft limit, and chunks larger than this value can be created. Must be larger than chunk_size. | an integer between 100MB and 10TB; default `5GB`.
  `chunk_size` | the maximum size of the in-memory chunk of an LSM tree. This limit is soft - it is possible for chunks to be temporarily larger than this value. This overrides the `memory_page_max` setting. | an integer between 512K and 500MB; default `10MB`.
  `merge_custom = (` | configure the tree to merge into a custom data source. | a set of related configuration options defined below.
  `prefix` | custom data source prefix instead of `"file"`. | a string; default empty.
  `start _generation` | merge generation at which the custom data source is used (zero indicates no custom data source). | an integer between 0 and 10; default `0`.
  `suffix` | custom data source suffix instead of `".lsm"`. | a string; default empty.
  `)` |  |
  `merge_max` | the maximum number of chunks to include in a merge operation. | an integer between 2 and 100; default `15`.
  `merge_min` | the minimum number of chunks to include in a merge operation. If set to 0 or 1 half the value of merge_max is used. | an integer no more than 100; default `0`.
  `)` |  |
  `memory_page_max` | the maximum size a page can grow to in memory before being reconciled to disk. The specified size will be adjusted to a lower bound of `leaf_page_max`, and an upper bound of `cache_size / 10`. This limit is soft - it is possible for pages to be temporarily larger than this value. This setting is ignored for LSM trees, see `chunk_size`. | an integer between 512B and 10TB; default `5MB`.
  `os_cache_dirty_max` | maximum dirty system buffer cache usage, in bytes. If non-zero, schedule writes for dirty blocks belonging to this object in the system buffer cache after that many bytes from this object are written into the buffer cache. | an integer greater than or equal to 0; default `0`.
  `os_cache_max` | maximum system buffer cache usage, in bytes. If non-zero, evict object blocks from the system buffer cache after that many bytes from this object are read or written into the buffer cache. | an integer greater than or equal to 0; default `0`.
  `prefix_compression` | configure prefix compression on row-store leaf pages. | a boolean flag; default `false`.
  `prefix_compression_min` | minimum gain before prefix compression will be used on row-store leaf pages. | an integer greater than or equal to 0; default `4`.
  `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 50 and 100; default `90`.
  `type` | set the type of data source used to store a column group, index or simple table. By default, a `"file:"` URI is derived from the object name. The `type` configuration can be used to switch to a different data source, such as LSM or an extension configured by the application. | a string; default `file`.
  `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 handling for details.

## ◆ drop()

int com.wiredtiger.db.Session.drop | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Drop (delete) an object.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

error_check(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`.
  `remove_files` | if the underlying files should be removed. | a boolean flag; default `true`.

Returns
  zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

## ◆ join()

int com.wiredtiger.db.Session.join | ( | Cursor | join_cursor,
|  | Cursor | ref_cursor,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Join a join cursor with a reference cursor.

/* Open cursors needed by the join. */
error_check(session->open_cursor(session,
"join:table:poptable", NULL, NULL, &join_cursor));
error_check(session->open_cursor(session,
"index:poptable:country", NULL, NULL, &country_cursor));
error_check(session->open_cursor(session,
"index:poptable:immutable_year", NULL, NULL, &year_cursor));
/* select values WHERE country == "AU" AND year > 1900 */
country_cursor->set_key(country_cursor, "AU\0\0\0");
error_check(country_cursor->search(country_cursor));
error_check(session->join(
session, join_cursor, country_cursor, "compare=eq,count=10"));
year_cursor->set_key(year_cursor, (uint16_t)1900);
error_check(year_cursor->search(year_cursor));
error_check(session->join(session,
join_cursor, year_cursor, "compare=gt,count=10,strategy=bloom"));
/* List the values that are joined */
while ((ret = join_cursor->next(join_cursor)) == 0) {
error_check(join_cursor->get_key(join_cursor, &recno));
error_check(join_cursor->get_value(
join_cursor, &country, &year, &population));
printf("ID %" PRIu64, recno);
printf(
": country %s, year %" PRIu16 ", population %" PRIu64 "\n",
country, year, population);
}
scan_end_check(ret == WT_NOTFOUND);

Parameters

  session | the session handle
  join_cursor | a cursor that was opened using a `"join:"` URI. It may not have been used for any operations other than other join calls.
  ref_cursor | an index cursor having the same base table as the join_cursor, or a table cursor open on the same base table, or another join cursor. Unless the ref_cursor is another join cursor, it must be positioned.

The ref_cursor limits the results seen by iterating the join_cursor to table items referred to by the key in this index. The set of keys referred to is modified by the compare config option.

Multiple join calls builds up a set of ref_cursors, and by default, the results seen by iteration are the intersection of the cursor ranges participating in the join. When configured with `"operation=or"`, the results seen are the union of the participating cursor ranges.

After the join call completes, the ref_cursor cursor may not be used for any purpose other than get_key and get_value. Any other cursor method (e.g. next, prev,close) will fail. When the join_cursor is closed, the ref_cursor is made available for general use again. The application should close ref_cursor when finished with it, although not before the join_cursor is closed.

Parameters

  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `bloom_bit_count` | the number of bits used per item for the bloom filter. | an integer between 2 and 1000; default `16`.
  `bloom_false_positives` | return all values that pass the bloom filter, without eliminating any false positives. | a boolean flag; default `false`.
  `bloom_hash_count` | the number of hash values per item for the bloom filter. | an integer between 2 and 100; default `8`.
  `compare` | modifies the set of items to be returned so that the index key satisfies the given comparison relative to the key set in this cursor. | a string, chosen from the following options: `"eq"`, `"ge"`, `"gt"`, `"le"`, `"lt"`; default `"eq"`.
  `count` | set an approximate count of the elements that would be included in the join. This is used in sizing the bloom filter, and also influences evaluation order for cursors in the join. When the count is equal for multiple bloom filters in a composition of joins, the bloom filter may be shared. | an integer; default ``.
  `operation` | the operation applied between this and other joined cursors. When "operation=and" is specified, all the conditions implied by joins must be satisfied for an entry to be returned by the join cursor; when "operation=or" is specified, only one must be satisfied. All cursors joined to a join cursor must have matching operations. | a string, chosen from the following options: `"and"`, `"or"`; default `"and"`.
  `strategy` | when set to bloom, a bloom filter is created and populated for this index. This has an up front cost but may reduce the number of accesses to the main table when iterating the joined cursor. The bloom setting requires that count be set. | a string, chosen from the following options: `"bloom"`, `"default"`; default empty.

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

## ◆ log_flush()

int com.wiredtiger.db.Session.log_flush | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Flush the log.

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `sync` | forcibly flush the log and wait for it to achieve the synchronization level specified. The `background` setting initiates a background synchronization intended to be used with a later call to WT_SESSION::transaction_sync. The `off` setting forces any buffered log records to be written to the file system. The `on` setting forces log records to be written to the storage device. | a string, chosen from the following options: `"background"`, `"off"`, `"on"`; default `on`.

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

## ◆ log_printf()

int com.wiredtiger.db.Session.log_printf | ( | String | format | ) | throws com.wiredtiger.db.WiredTigerException

Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called).

Parameters

  session | the session handle
  format | a printf format specifier

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

## ◆ open_cursor()

Cursor com.wiredtiger.db.Session.open_cursor | ( | String | uri,
|  | Cursor | to_dup,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

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

error_check(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:`

error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor));
cursor->set_key(cursor, key);
error_check(cursor->search(cursor));
/* Duplicate the cursor. */
error_check(
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.

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.

WT_SESSION::rollback_transaction implicitly resets all 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 basic cursor types:

URI | Type | Notes
--- | --- | ---
`table:<table name>[<projection>]` | table cursor | table key, table value(s) with optional projection of columns
`colgroup:<table name>:<column group name>` | column group cursor | table key, column group value(s)
`index:<table name>:<index name>[<projection>]` | index cursor | key=index key, value=table value(s) with optional projection of columns
`join:table:<table name>[<projection>]` | join cursor | key=table key, value=table value(s) with optional projection of columns

Some administrative tasks can be accomplished using the following special cursor types that give access to data managed by WiredTiger:

URI | Type | Notes
--- | --- | ---
`backup:` | backup cursor | key=`string`, see Backups for details
`log:` | log cursor | key=`(long fileID, long offset, int seqno)`, value=`(uint64_t txnid, uint32_t rectype, uint32_t optype, uint32_t fileid, WT_ITEM key, WT_ITEM value)`, see Log cursors for details
`metadata:[create]` | metadata cursor (optionally only returning configuration strings for WT_SESSION::create if `create` is appended | key=`string`, value=`string`, see Reading WiredTiger Metadata for details
`statistics:[<data source URI>]` | database | data source or join statistics cursor | key=`int id`, value=`(string description, string value, uint64_t value)`, see Statistics Data for details

Advanced applications may also open the following low-level cursor types:

URI | Type | Notes
--- | --- | ---
`file:<file name>` | file cursor | file key, file value(s)
`lsm:<name>` | LSM cursor (key=LSM key, value=LSM value) | LSM key, LSM value, see Log-Structured Merge Trees

Parameters

  | to_dup | a cursor to duplicate or gather statistics on
  | 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-loading, a fast, initial load path (see Bulk-load for more information). Bulk-load may only be used for newly created objects and applications should use the WT_CURSOR::insert method to insert rows. When bulk-loading, rows must be loaded in sorted order. The value is usually a true/false flag; when bulk-loading fixed-length column store objects, the special value `bitmap` allows chunks of a memory resident bitmap to be loaded directly into a file by passing a `WT_ITEM` to WT_CURSOR::set_value where the `size` field indicates the number of records in the bitmap (as specified by the object's `value_format` configuration). Bulk-loaded bitmap values must end on a byte boundary relative to the bit count (except for the last set of values loaded). | a string; default `false`.
  `checkpoint` | the name of a checkpoint to open (the reserved name "WiredTigerCheckpoint" opens the most recent internal checkpoint taken for the object). The cursor does not support data modification. | a string; default empty.
  `dump` | configure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "json" selects a JSON format with each record formatted as fields named by column names if available, and "print" selects a format where only non-printing characters are hexadecimal encoded. These formats are compatible with the wt dump and wt load commands. | a string, chosen from the following options: `"hex"`, `"json"`, `"print"`; default empty.
  `next_random` | configure the cursor to return a pseudo-random record from the object when the WT_CURSOR::next method is called; valid only for row-store cursors. See Cursor random for details. | a boolean flag; default `false`.
  `next_random_sample_size` | cursors configured by `next_random` to return pseudo-random records from the object randomly select from the entire object, by default. Setting `next_random_sample_size` to a non-zero value sets the number of samples the application expects to take using the `next_random` cursor. A cursor configured with both `next_random` and `next_random_sample_size` attempts to divide the object into `next_random_sample_size` equal-sized pieces, and each retrieval returns a record from one of those pieces. See Cursor random for details. | a string; default `0`.
  `overwrite` | configures 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`.
  `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`.
  `readonly` | only query operations are supported by this cursor. An error is returned if a modification is attempted using the cursor. The default is false for all cursor types except for log and metadata cursors. | a boolean flag; default `false`.
  `statistics` | Specify the statistics to be gathered. Choosing "all" gathers statistics regardless of cost and may include traversing on-disk files; "fast" gathers a subset of relatively inexpensive statistics. The selection must agree with the database `statistics` configuration specified to wiredtiger_open or WT_CONNECTION::reconfigure. For example, "all" or "fast" can be configured when the database is configured with "all", but the cursor open will fail if "all" is specified when the database is configured with "fast", and the cursor open will fail in all cases when the database is configured with "none". If "size" is configured, only the underlying size of the object on disk is filled in and the object is not opened. If `statistics` is not configured, the default configuration is the database configuration. The "clear" configuration resets statistics after gathering them, where appropriate (for example, a cache size statistic is not cleared, while the count of cursor insert operations will be cleared). See Statistics for more information. | a list, with values chosen from the following options: `"all"`, `"cache_walk"`, `"fast"`, `"clear"`, `"size"`, `"tree_walk"`; default empty.
  `target` | if non-empty, backup the list of objects; valid only for a backup data source. | a list of strings; default empty.
  [out] | cursorp | a pointer to the newly opened cursor

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

## ◆ prepare_transaction()

int com.wiredtiger.db.Session.prepare_transaction | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Prepare the current transaction.

A transaction must be in progress when this method is called.

Preparing a transaction will guarantee a subsequent commit will succeed. Only commit and rollback are allowed on a transaction after it has been prepared. The transaction prepare API is designed to support MongoDB exclusively, and guarantees update conflicts have been resolved, but does not guarantee durability.

This method must be called on a session with an active transaction.

/*
* Prepare a transaction which guarantees a subsequent commit will
* succeed. Only commit and rollback are allowed on a transaction after
* it has been prepared.
*/
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
error_check(session->prepare_transaction(
session, "prepare_timestamp=2a"));
error_check(session->commit_transaction(
session, "commit_timestamp=2b"));

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `prepare_timestamp` | set the prepare timestamp for the updates of the current transaction. The supplied value must not be older than any active read timestamps. This configuration option is mandatory. See Application-specified Transaction Timestamps. | a string; default empty.

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

## ◆ rebalance()

int com.wiredtiger.db.Session.rebalance | ( | String | uri,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Rebalance a table or file, see Rebalance.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

error_check(session->rebalance(session, "table:mytable", NULL));

Parameters

  session | the session handle
  uri | the current URI of the object, such as `"table:mytable"`
  config | configuration string, see Configuration Strings. No values currently permitted.

Returns
  zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

## ◆ reconfigure()

int com.wiredtiger.db.Session.reconfigure | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Reconfigure a session handle.

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

WT_SESSION::reconfigure will fail if a transaction is in progress in the session.

All cursors are reset.

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `cache_cursors` | enable caching of cursors for reuse. Any calls to WT_CURSOR::close for a cursor created in this session will mark the cursor as cached and keep it available to be reused for later calls to WT_SESSION::open_cursor. Cached cursors may be eventually closed. This value is inherited from wiredtiger_open `cache_cursors`. | a boolean flag; default `true`.
  `ignore_cache_size` | when set, operations performed by this session ignore the cache size and are not blocked when the cache is full. Note that use of this option for operations that create cache pressure can starve ordinary sessions that obey the cache size. | a boolean flag; default `false`.
  `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 handling for details.

## ◆ rename()

int com.wiredtiger.db.Session.rename | ( | String | uri,
|  | String | newuri,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Rename an object.

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

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

Parameters

  session | the session handle
  uri | the current URI of the object, such as `"table:old"`
  newuri | the new URI of the object, such as `"table:new"`
  config | configuration string, see Configuration Strings. No values currently permitted.

Returns
  zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

## ◆ reset()

int com.wiredtiger.db.Session.reset | ( |  | ) | throws com.wiredtiger.db.WiredTigerException

Reset the session handle.

This method resets all cursors associated with this session and discards cached resources. The session can be re-used immediately after this call returns. If a transaction is running on this session, then this call takes no action and return an error.

error_check(session->reset(session));

Parameters

  session | the session handle

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

## ◆ rollback_transaction()

int com.wiredtiger.db.Session.rollback_transaction | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Roll back the current transaction.

A transaction must be in progress when this method is called.

All cursors are reset.

This method must be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* Opening cursors before the transaction begins allows applications to
* cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all 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 handling for details.

## ◆ salvage()

int com.wiredtiger.db.Session.salvage | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Salvage a table or file.

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 table or file has been corrupted, as reported by the WT_SESSION::verify method.

Files are rebuilt in place, the salvage method overwrites the existing files.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

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

Parameters

  session | the session handle
  name | the URI of the table or file 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, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

## ◆ snapshot()

int com.wiredtiger.db.Session.snapshot | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Manage named snapshot transactions.

Use this API to create and drop named snapshots. Named snapshot transactions can be accessed via WT_CURSOR::open. See Named Snapshots.

/* Create a named snapshot */
error_check(session->snapshot(session, "name=June01"));
/* Open a transaction at a given snapshot */
error_check(session->begin_transaction(session, "snapshot=June01"));
/* Drop all named snapshots */
error_check(session->snapshot(session, "drop=(all)"));

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `drop = (` | if non-empty, specifies which snapshots to drop. Where a group of snapshots are being dropped, the order is based on snapshot creation order not alphanumeric name order. | a set of related configuration options defined below.
  `all` | drop all named snapshots. | a boolean flag; default `false`.
  `before` | drop all snapshots up to but not including the specified name. | a string; default empty.
  `names` | drop specific named snapshots. | a list of strings; default empty.
  `to` | drop all snapshots up to and including the specified name. | a string; default empty.
  `)` |  |
  `include_updates` | make updates from the current transaction visible to users of the named snapshot. Transactions started with such a named snapshot are restricted to being read-only. | a boolean flag; default `false`.
  `name` | specify a name for the snapshot. | a string; default empty.

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

## ◆ timestamp_transaction()

int com.wiredtiger.db.Session.timestamp_transaction | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Set a timestamp on a transaction.

error_check(
session->timestamp_transaction(session, "commit_timestamp=2a"));

This method must be called on a session with an active transaction.

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `commit_timestamp` | set the commit timestamp for the current transaction. The supplied value must not be older than the first commit timestamp set for the current transaction. The value must also not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps. | a string; default empty.
  `read_timestamp` | read using the specified timestamp. The supplied value must not be older than the current oldest timestamp. This can only be set once for a transaction. Application-specified Transaction Timestamps. | a string; default empty.
  `round_to_oldest` | if read timestamp is earlier than oldest timestamp, read timestamp will be rounded to oldest timestamp. | a boolean flag; default `false`.

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

## ◆ transaction_pinned_range()

int com.wiredtiger.db.Session.transaction_pinned_range | ( |  | ) | throws com.wiredtiger.db.WiredTigerException

Return the transaction ID range pinned by the session handle.

The ID range is approximate and is calculated based on the oldest ID needed for the active transaction in this session, compared to the newest transaction in the system.

/* Check the transaction ID range pinned by the session handle. */
uint64_t range;
error_check(session->transaction_pinned_range(session, &range));

Parameters

  | session | the session handle
  [out] | range | the range of IDs pinned by this session. Zero if there is no active transaction.

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

## ◆ transaction_sync()

int com.wiredtiger.db.Session.transaction_sync | ( | String | config | ) | throws com.wiredtiger.db.WiredTigerException

Wait for a transaction to become synchronized.

This method is only useful when wiredtiger_open is configured with the `transaction_sync` setting disabled.

This method must not be called on a session with an active transaction.

error_check(session->transaction_sync(session, NULL));

Parameters

  session | the session handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `timeout_ms` | maximum amount of time to wait for background sync to complete in milliseconds. A value of zero disables the timeout and returns immediately. | an integer; default `1200000`.

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

## ◆ truncate()

int com.wiredtiger.db.Session.truncate | ( | String | name,
|  | Cursor | start,
|  | Cursor | stop,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Truncate a file, table or cursor range.

Truncate a table or file.

error_check(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;
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &start));
start->set_key(start, "June01");
error_check(start->search(start));
error_check(session->open_cursor(
session, "table:mytable", NULL, NULL, &stop));
stop->set_key(stop, "June30");
error_check(stop->search(stop));
error_check(session->truncate(session, NULL, start, stop, NULL));

Any specified cursors end with no position, and subsequent calls to the WT_CURSOR::next (WT_CURSOR::prev) method will iterate from the beginning (end) of the table.

Parameters

  session | the session handle
  name | the URI of the table or file 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 handling for details.

## ◆ upgrade()

int com.wiredtiger.db.Session.upgrade | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Upgrade a table or file.

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

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

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

Parameters

  session | the session handle
  name | the URI of the table or file to upgrade
  config | configuration string, see Configuration Strings. No values currently permitted.

Returns
  zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

## ◆ verify()

int com.wiredtiger.db.Session.verify | ( | String | name,
|  | String | config
| ) |  | throws com.wiredtiger.db.WiredTigerException

Verify a table or file.

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,

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

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return `EBUSY`.

Parameters

  session | the session handle
  name | the URI of the table or file to verify
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `dump_address` | Display addresses and page types as pages are verified, using the application's message handler, intended for debugging. | a boolean flag; default `false`.
  `dump_blocks` | Display the contents of on-disk blocks as they are verified, using the application's message handler, intended for debugging. | a boolean flag; default `false`.
  `dump_layout` | Display the layout of the files as they are verified, using the application's message handler, intended for debugging; requires optional support from the block manager. | a boolean flag; default `false`.
  `dump_offsets` | Display the contents of specific on-disk blocks, using the application's message handler, intended for debugging. | a list of strings; default empty.
  `dump_pages` | Display the contents of in-memory pages as they are verified, using the application's message handler, intended for debugging. | a boolean flag; default `false`.
  `strict` | Treat any verification problem as an error; by default, verify will warn, but not fail, in the case of errors that won't affect future behavior (for example, a leaked block). | a boolean flag; default `false`.

Returns
  zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.