Version 3.2.1
com.wiredtiger.db.Connection Class Reference

A connection to a WiredTiger database. More...

Public Member Functions

synchronized void delete ()
 
int async_flush () throws com.wiredtiger.db.WiredTigerException
 Wait for all outstanding operations to complete. More...
 
int close (String config) throws com.wiredtiger.db.WiredTigerException
 Close a connection. More...
 
int debug_info (String config) throws com.wiredtiger.db.WiredTigerException
 
int reconfigure (String config) throws com.wiredtiger.db.WiredTigerException
 Reconfigure a connection handle. More...
 
String get_home ()
 
int configure_method (String method, String uri, String config, String type, String check) throws com.wiredtiger.db.WiredTigerException
 Add configuration options for a method. More...
 
int is_new ()
 Return if opening this handle created the database. More...
 
int query_timestamp (String hex_timestamp, String config) throws com.wiredtiger.db.WiredTigerException
 Query the global transaction timestamp state. More...
 
int set_timestamp (String config) throws com.wiredtiger.db.WiredTigerException
 Set a global transaction timestamp. More...
 
int rollback_to_stable (String config) throws com.wiredtiger.db.WiredTigerException
 Rollback in-memory non-logged state to an earlier point in time. More...
 
int load_extension (String path, String config) throws com.wiredtiger.db.WiredTigerException
 Load an extension. More...
 
AsyncOp async_new_op (String uri, String config, Object callbackObject) throws com.wiredtiger.db.WiredTigerException
 Return an async operation handle. More...
 
Session open_session (String config) throws com.wiredtiger.db.WiredTigerException
 Open a session. More...
 

Protected Member Functions

 Connection (long cPtr, boolean cMemoryOwn)
 
int _java_init (Object jsess)
 

Static Protected Member Functions

static long getCPtr (Connection obj)
 

Protected Attributes

boolean swigCMemOwn
 

Detailed Description

A connection to a WiredTiger database.

The connection may be opened within the same address space as the caller or accessed over a socket connection.

Most applications will open a single connection to a database for each process. The first process to open a connection to a database will access the database in its own address space. Subsequent connections (if allowed) will communicate with the first process over a socket connection to perform their operations.

Thread safety: A WT_CONNECTION handle may be shared between threads, see Multithreading for more information.

Member Function Documentation

◆ async_flush()

int com.wiredtiger.db.Connection.async_flush ( ) throws com.wiredtiger.db.WiredTigerException

Wait for all outstanding operations to complete.

/* Wait for all outstanding operations to complete. */
error_check(conn->async_flush(conn));
Parameters
connectionthe connection handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ async_new_op()

AsyncOp com.wiredtiger.db.Connection.async_new_op ( String  uri,
String  config,
Object  callbackObject 
) throws com.wiredtiger.db.WiredTigerException

Return an async operation handle.

while (
(ret = conn->async_new_op(conn, "table:async", NULL, &ex_asynckeys.iface, &op)) != 0) {
/*
* If we used up all the handles, pause and retry to give the workers a chance to catch
* up.
*/
fprintf(stderr, "asynchronous operation handle not available\n");
if (ret == EBUSY)
sleep(1);
else
return (EXIT_FAILURE);
}
Parameters
connectionthe connection handle
urithe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
appendappend the value as a new record, creating a new record number key; valid only for operations with record number keys.a boolean flag; default false.
overwriteconfigures 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.
rawignore 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.
timeoutmaximum 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.
callbackthe operation callback
[out]asyncoppthe new op handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details. If there are no available handles, EBUSY is returned.

◆ close()

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

Close a connection.

Any open sessions will be closed. 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(conn->close(conn, NULL));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
leak_memorydon't free memory during close.a boolean flag; default false.
use_timestampby default, create the close 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.a boolean flag; default true.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ configure_method()

int com.wiredtiger.db.Connection.configure_method ( String  method,
String  uri,
String  config,
String  type,
String  check 
) throws com.wiredtiger.db.WiredTigerException

Add configuration options for a method.

See Creating data-specific configuration strings for more information.

/*
* Applications opening a cursor for the data-source object "my_data"
* have an additional configuration option "entries", which is an
* integer type, defaults to 5, and must be an integer between 1 and 10.
*
* The method being configured is specified using a concatenation of the
* handle name, a period and the method name.
*/
error_check(conn->configure_method(
conn, "WT_SESSION.open_cursor", "my_data:", "entries=5", "int", "min=1,max=10"));
/*
* Applications opening a cursor for the data-source object "my_data" have an additional
* configuration option "devices", which is a list of strings.
*/
error_check(
conn->configure_method(conn, "WT_SESSION.open_cursor", "my_data:", "devices", "list", NULL));
Parameters
connectionthe connection handle
methodthe method being configured
urithe object type or NULL for all object types
configthe additional configuration's name and default value
typethe additional configuration's type (must be one of "boolean"\, "int", "list" or "string")
checkthe additional configuration check string, or NULL if none
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ debug_info()

int com.wiredtiger.db.Connection.debug_info ( String  config) throws com.wiredtiger.db.WiredTigerException

◆ is_new()

int com.wiredtiger.db.Connection.is_new ( )

Return if opening this handle created the database.

if (conn->is_new(conn)) {
/* First time initialization. */
}
Parameters
connectionthe connection handle
Returns
false (zero) if the connection existed before the call to wiredtiger_open, true (non-zero) if it was created by opening this handle.

◆ load_extension()

int com.wiredtiger.db.Connection.load_extension ( String  path,
String  config 
) throws com.wiredtiger.db.WiredTigerException

Load an extension.

error_check(conn->load_extension(conn, "my_extension.dll", NULL));
error_check(conn->load_extension(
conn, "datasource/libdatasource.so", "config=[device=/dev/sd1,alignment=64]"));
Parameters
connectionthe connection handle
paththe filename of the extension module, or "local" to search the current application binary for the initialization function, see Extending WiredTiger for more details.
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
configconfiguration string passed to the entry point of the extension as its WT_CONFIG_ARG argument.a string; default empty.
early_loadwhether this extension should be loaded at the beginning of wiredtiger_open. Only applicable to extensions loaded via the wiredtiger_open configurations string.a boolean flag; default false.
entrythe entry point of the extension, called to initialize the extension when it is loaded. The signature of the function must match wiredtiger_extension_init.a string; default wiredtiger_extension_init.
terminatean optional function in the extension that is called before the extension is unloaded during WT_CONNECTION::close. The signature of the function must match wiredtiger_extension_terminate.a string; default wiredtiger_extension_terminate.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ open_session()

Session com.wiredtiger.db.Connection.open_session ( String  config) throws com.wiredtiger.db.WiredTigerException

Open a session.

WT_SESSION *session;
error_check(conn->open_session(conn, NULL, NULL, &session));
Parameters
connectionthe connection handle
event_handlerAn event handler. If NULL, the connection's event handler is used. See Message handling using the WT_EVENT_HANDLER for more information.
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
cache_cursorsenable 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_sizewhen 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.
isolationthe default isolation level for operations in this session.a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default read-committed.
[out]sessionpthe new session handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ query_timestamp()

int com.wiredtiger.db.Connection.query_timestamp ( String  hex_timestamp,
String  config 
) throws com.wiredtiger.db.WiredTigerException

Query the global transaction timestamp state.

char timestamp_buf[2 * sizeof(uint64_t) + 1];
error_check(session->timestamp_transaction(session, "commit_timestamp=2a"));
error_check(session->commit_transaction(session, NULL));
error_check(conn->query_timestamp(conn, timestamp_buf, "get=all_committed"));
Parameters
connectionthe connection handle
[out]hex_timestampa buffer that will be set to the hexadecimal encoding of the timestamp being queried. Must be large enough to hold a NUL terminated, hex-encoded 8B timestamp (17 bytes).
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
getspecify which timestamp to query: all_committed returns the largest timestamp such that all timestamps up to that value have committed, all_durable returns the largest timestamp such that all timestamps up to that value have been made durable, last_checkpoint returns the timestamp of the most recent stable checkpoint, oldest returns the most recent oldest_timestamp set with WT_CONNECTION::set_timestamp, oldest_reader returns the minimum of the read timestamps of all active readers pinned returns the minimum of the oldest_timestamp and the read timestamps of all active readers, recovery returns the timestamp of the most recent stable checkpoint taken prior to a shutdown and stable returns the most recent stable_timestamp set with WT_CONNECTION::set_timestamp. See Application-specified Transaction Timestamps.a string, chosen from the following options: "all_committed", "all_durable", "last_checkpoint", "oldest", "oldest_reader", "pinned", "recovery", "stable"; default all_durable.
Returns
zero on success and a non-zero error code on failure. See Error handling for details. If there is no matching timestamp (e.g., if this method is called before timestamps are used) WT_NOTFOUND will be returned.

◆ reconfigure()

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

Reconfigure a connection handle.

error_check(conn->reconfigure(conn, "eviction_target=75"));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
async = (asynchronous operations configuration options.a set of related configuration options defined below.
    enabledenable asynchronous operation.a boolean flag; default false.
    ops_maxmaximum number of expected simultaneous asynchronous operations.an integer between 1 and 4096; default 1024.
    threadsthe number of worker threads to service asynchronous requests. Each worker thread uses a session from the configured session_max.an integer between 1 and 20; default 2.
)
cache_max_wait_msthe maximum number of milliseconds an application thread will wait for space to be available in cache before giving up. Default will wait forever.an integer greater than or equal to 0; default 0.
cache_overflow = (cache overflow configuration options.a set of related configuration options defined below.
    file_maxThe maximum number of bytes that WiredTiger is allowed to use for its cache overflow mechanism. If the cache overflow file exceeds this size, a panic will be triggered. The default value means that the cache overflow file is unbounded and may use as much space as the filesystem will accommodate. The minimum non-zero setting is 100MB.an integer greater than or equal to 0; default 0.
)
cache_overheadassume the heap allocator overhead is the specified percentage, and adjust the cache usage by that amount (for example, if there is 10GB of data in cache, a percentage of 10 means WiredTiger treats this as 11GB). This value is configurable because different heap allocators have different overhead and different workloads will have different heap allocation sizes and patterns, therefore applications may need to adjust this value based on allocator choice and behavior in measured workloads.an integer between 0 and 30; default 8.
cache_sizemaximum heap memory to allocate for the cache. A database should configure either cache_size or shared_cache but not both.an integer between 1MB and 10TB; default 100MB.
checkpoint = (periodically checkpoint the database. Enabling the checkpoint server uses a session from the configured session_max.a set of related configuration options defined below.
    log_sizewait for this amount of log record bytes to be written to the log between each checkpoint. If non-zero, this value will use a minimum of the log file size. A database can configure both log_size and wait to set an upper bound for checkpoints; setting this value above 0 configures periodic checkpoints.an integer between 0 and 2GB; default 0.
    waitseconds to wait between each checkpoint; setting this value above 0 configures periodic checkpoints.an integer between 0 and 100000; default 0.
)
compatibility = (set compatibility version of database. Changing the compatibility version requires that there are no active operations for the duration of the call.a set of related configuration options defined below.
    releasecompatibility release version string.a string; default empty.
)
debug_mode = (control the settings of various extended debugging features.a set of related configuration options defined below.
     checkpoint_retentionadjust log archiving to retain the log records of this number of checkpoints. Zero or one means perform normal archiving.an integer between 0 and 1024; default 0.
    evictionif true, modify internal algorithms to change skew to force lookaside eviction to happen more aggressively. This includes but is not limited to not skewing newest, not favoring leaf pages, and modifying the eviction score mechanism.a boolean flag; default false.
    rollback_errorreturn a WT_ROLLBACK error from a transaction operation about every Nth operation to simulate a collision.an integer between 0 and 10M; default 0.
    table_loggingif true, write transaction related information to the log for all operations, even operations for tables with logging turned off. This setting introduces a log format change that may break older versions of WiredTiger. These operations are informational and skipped in recovery.a boolean flag; default false.
)
error_prefixprefix string for error messages.a string; default empty.
eviction = (eviction configuration options.a set of related configuration options defined below.
    threads_maxmaximum number of threads WiredTiger will start to help evict pages from cache. The number of threads started will vary depending on the current eviction load. Each eviction worker thread uses a session from the configured session_max.an integer between 1 and 20; default 8.
    threads_minminimum number of threads WiredTiger will start to help evict pages from cache. The number of threads currently running will vary depending on the current eviction load.an integer between 1 and 20; default 1.
)
eviction_checkpoint_targetperform eviction at the beginning of checkpoints to bring the dirty content in cache to this level. It is a percentage of the cache size if the value is within the range of 0 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size. Ignored if set to zero or in_memory is true.an integer between 0 and 10TB; default 1.
eviction_dirty_targetperform eviction in worker threads when the cache contains at least this much dirty content. It is a percentage of the cache size if the value is within the range of 1 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size.an integer between 1 and 10TB; default 5.
eviction_dirty_triggertrigger application threads to perform eviction when the cache contains at least this much dirty content. It is a percentage of the cache size if the value is within the range of 1 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size. This setting only alters behavior if it is lower than eviction_trigger.an integer between 1 and 10TB; default 20.
eviction_targetperform eviction in worker threads when the cache contains at least this much content. It is a percentage of the cache size if the value is within the range of 10 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size.an integer between 10 and 10TB; default 80.
eviction_triggertrigger application threads to perform eviction when the cache contains at least this much content. It is a percentage of the cache size if the value is within the range of 10 to 100 or an absolute size when greater than 100. The value is not allowed to exceed the cache_size.an integer between 10 and 10TB; default 95.
file_manager = (control how file handles are managed.a set of related configuration options defined below.
     close_handle_minimumnumber of handles open before the file manager will look for handles to close.an integer greater than or equal to 0; default 250.
    close_idle_timeamount of time in seconds a file handle needs to be idle before attempting to close it. A setting of 0 means that idle handles are not closed.an integer between 0 and 100000; default 30.
    close_scan_intervalinterval in seconds at which to check for files that are inactive and close them.an integer between 1 and 100000; default 10.
)
io_capacity = (control how many bytes per second are written and read. Exceeding the capacity results in throttling.a set of related configuration options defined below.
    totalnumber of bytes per second available to all subsystems in total. When set, decisions about what subsystems are throttled, and in what proportion, are made internally. The minimum non-zero setting is 1MB.an integer between 0 and 1TB; default 0.
)
log = (enable logging. Enabling logging uses three sessions from the configured session_max.a set of related configuration options defined below.
    archiveautomatically archive unneeded log files.a boolean flag; default true.
    os_cache_dirty_pctmaximum dirty system buffer cache usage, as a percentage of the log's file_max. If non-zero, schedule writes for dirty blocks belonging to the log in the system buffer cache after that percentage of the log has been written into the buffer cache without an intervening file sync.an integer between 0 and 100; default 0.
    preallocpre-allocate log files.a boolean flag; default true.
    zero_fillmanually write zeroes into log files.a boolean flag; default false.
)
lsm_manager = (configure database wide options for LSM tree management. The LSM manager is started automatically the first time an LSM tree is opened. The LSM manager uses a session from the configured session_max.a set of related configuration options defined below.
    mergemerge LSM chunks where possible.a boolean flag; default true.
     worker_thread_maxConfigure a set of threads to manage merging LSM trees in the database. Each worker thread uses a session handle from the configured session_max.an integer between 3 and 20; default 4.
)
operation_tracking = (enable tracking of performance-critical functions. See Track function calls for more information.a set of related configuration options defined below.
    enabledenable operation tracking subsystem.a boolean flag; default false.
    paththe name of a directory into which operation tracking files are written. The directory must already exist. If the value is not an absolute path, the path is relative to the database home (see Absolute paths for more information).a string; default ".".
)
shared_cache = (shared cache configuration options. A database should configure either a cache_size or a shared_cache not both. Enabling a shared cache uses a session from the configured session_max. A shared cache can not have absolute values configured for cache eviction settings.a set of related configuration options defined below.
    chunkthe granularity that a shared cache is redistributed.an integer between 1MB and 10TB; default 10MB.
    namethe name of a cache that is shared between databases or "none" when no shared cache is configured.a string; default none.
    quotamaximum size of cache this database can be allocated from the shared cache. Defaults to the entire shared cache size.an integer; default 0.
    reserveamount of cache this database is guaranteed to have available from the shared cache. This setting is per database. Defaults to the chunk size.an integer; default 0.
     sizemaximum memory to allocate for the shared cache. Setting this will update the value if one is already set.an integer between 1MB and 10TB; default 500MB.
)
statisticsMaintain database statistics, which may impact performance. Choosing "all" maintains all statistics regardless of cost, "fast" maintains a subset of statistics that are relatively inexpensive, "none" turns off all statistics. The "clear" configuration resets statistics after they are gathered, where appropriate (for example, a cache size statistic is not cleared, while the count of cursor insert operations will be cleared). When "clear" is configured for the database, gathered statistics are reset each time a statistics cursor is used to gather statistics, as well as each time statistics are logged using the statistics_log configuration. See Statistics for more information.a list, with values chosen from the following options: "all", "cache_walk", "fast", "none", "clear", "tree_walk"; default none.
statistics_log = (log any statistics the database is configured to maintain, to a file. See Statistics for more information. Enabling the statistics log server uses a session from the configured session_max.a set of related configuration options defined below.
    jsonencode statistics in JSON format.a boolean flag; default false.
    on_closelog statistics on database close.a boolean flag; default false.
    sourcesif non-empty, include statistics for the list of data source URIs, if they are open at the time of the statistics logging. The list may include URIs matching a single data source ("table:mytable"), or a URI matching all data sources of a particular type ("table:").a list of strings; default empty.
    timestampa timestamp prepended to each log record, may contain strftime conversion specifications, when json is configured, defaults to "%FT%Y.000Z".a string; default "%b %d %H:%M:%S".
     waitseconds to wait between each write of the log records; setting this value above 0 configures statistics logging.an integer between 0 and 100000; default 0.
)
verboseenable messages for various events. Options are given as a list, such as "verbose=[evictserver,read]".a list, with values chosen from the following options: "api", "block", "checkpoint", "checkpoint_progress", "compact", "compact_progress", "error_returns", "evict", "evict_stuck", "evictserver", "fileops", "handleops", "log", "lookaside", "lookaside_activity", "lsm", "lsm_manager", "metadata", "mutex", "overflow", "read", "rebalance", "reconcile", "recovery", "recovery_progress", "salvage", "shared_cache", "split", "temporary", "thread_group", "timestamp", "transaction", "verify", "version", "write"; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ rollback_to_stable()

int com.wiredtiger.db.Connection.rollback_to_stable ( String  config) throws com.wiredtiger.db.WiredTigerException

Rollback in-memory non-logged state to an earlier point in time.

This method uses a timestamp to define the rollback point, and thus requires that the application uses timestamps and that the stable_timestamp must have been set via a call to WT_CONNECTION::set_timestamp. Any updates to checkpoint durable tables that are more recent than the stable timestamp are removed.

This method requires that there are no active operations for the duration of the call.

Any updates made to logged tables will not be rolled back. Any updates made without an associated timestamp will not be rolled back. See Application-specified Transaction Timestamps.

error_check(conn->rollback_to_stable(conn, NULL));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ set_timestamp()

int com.wiredtiger.db.Connection.set_timestamp ( String  config) throws com.wiredtiger.db.WiredTigerException

Set a global transaction timestamp.

error_check(conn->set_timestamp(conn, "commit_timestamp=2a"));
error_check(conn->set_timestamp(conn, "oldest_timestamp=2a"));
error_check(conn->set_timestamp(conn, "stable_timestamp=2a"));
Parameters
connectionthe connection handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
commit_timestamp(deprecated) reset the maximum commit timestamp tracked by WiredTiger. This will cause future calls to WT_CONNECTION::query_timestamp to ignore commit timestamps greater than the specified value until the next commit moves the tracked commit timestamp forwards. This is only intended for use where the application is rolling back locally committed transactions. The supplied value must not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps.a string; default empty.
durable_timestampreset the maximum durable timestamp tracked by WiredTiger. This will cause future calls to WT_CONNECTION::query_timestamp to ignore durable timestamps greater than the specified value until the next durable timestamp moves the tracked durable timestamp forwards. This is only intended for use where the application is rolling back locally committed transactions. The supplied value must not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps.a string; default empty.
forceset timestamps even if they violate normal ordering requirements. For example allow the oldest_timestamp to move backwards.a boolean flag; default false.
oldest_timestampfuture commits and queries will be no earlier than the specified timestamp. Supplied values must be monotonically increasing, any attempt to set the value to older than the current is silently ignored. The supplied value must not be newer than the current stable timestamp. See Application-specified Transaction Timestamps.a string; default empty.
stable_timestampcheckpoints will not include commits that are newer than the specified timestamp in tables configured with log=(enabled=false). Supplied values must be monotonically increasing, any attempt to set the value to older than the current is silently ignored. The supplied value must not be older than the current oldest timestamp. 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.