All data operations are performed in the context of a WT_SESSION. More...
Public Member Functions | |
int | close (WT_SESSION *session, const char *config) |
Close the session handle. | |
Cursor handles | |
int | open_cursor (WT_SESSION *session, const char *uri, WT_CURSOR *to_dup, const char *config, WT_CURSOR **cursorp) |
Open a cursor. | |
Table operations | |
int | create (WT_SESSION *session, const char *name, const char *config) |
Create a table, column group, index or file. | |
int | drop (WT_SESSION *session, const char *name, const char *config) |
Drop (delete) an object. | |
int | rename (WT_SESSION *session, const char *oldname, const char *newname, const char *config) |
Rename an object. | |
int | salvage (WT_SESSION *session, const char *name, const char *config) |
Salvage a file or table. | |
int | sync (WT_SESSION *session, const char *name, const char *config) |
Sync a file or table. | |
int | truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config) |
Truncate a file, table or a cursor range. | |
int | upgrade (WT_SESSION *session, const char *name, const char *config) |
Upgrade a file or table. | |
int | verify (WT_SESSION *session, const char *name, const char *config) |
Verify a file or table. | |
Transactions | |
int | begin_transaction (WT_SESSION *session, const char *config) |
Start a transaction in this session. | |
int | commit_transaction (WT_SESSION *session, const char *config) |
Commit the current transaction. | |
int | rollback_transaction (WT_SESSION *session, const char *config) |
Roll back the current transaction. | |
int | checkpoint (WT_SESSION *session, const char *config) |
Flush the cache and/or the log and optionally archive log files. | |
Debugging | |
int | dumpfile (WT_SESSION *session, const char *name, const char *config) |
Dump a physical file in debugging mode. | |
int | msg_printf (WT_SESSION *session, const char *fmt,...) |
Send a string to the message handler for debugging. | |
Public Attributes | |
WT_CONNECTION * | connection |
The connection for this session. |
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 cannot be shared between threads: it may only be used within a single thread. Each thread accessing a database should open a separate WT_SESSION handle.
int WT_SESSION::begin_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Start a transaction in this session.
Not yet supported in WiredTiger.
All cursors opened in this session that support transactional semantics will operate in the context of the transaction. The transaction remains active until ended with WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction.
Ignored if a transaction is in progress.
ret = session->begin_transaction(session, NULL);
session | the session handle | |||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::checkpoint | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Flush the cache and/or the log and optionally archive log files.
Not yet supported in WiredTiger.
ret = session->checkpoint(session, NULL);
session | the session handle | |||||||||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::close | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Close the session handle.
This will release the resources associated with the session handle, including rolling any active transactions and closing any cursors that remain open in the session.
ret = session->close(session, NULL);
session | the session handle |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::commit_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Commit the current transaction.
Not yet supported in WiredTiger.
Any cursors opened during the transaction will be closed before the commit is processed.
Ignored if no transaction is in progress.
ret = session->commit_transaction(session, NULL);
session | the session handle |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::create | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Create a table, column group, index or file.
ret = session->create(session, "table:mytable", "key_format=S,value_format=S");
session | the session handle | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | the URI of the object to create, such as "table:stock" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::drop | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Drop (delete) an object.
ret = session->drop(session, "table:mytable", NULL);
session | the session handle | ||||||
name | the URI of the object to drop, such as "table:stock" | ||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::dumpfile | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Dump a physical file in debugging mode.
The specified file is displayed in a non-portable debugging mode to the application's standard output.
ret = session->dumpfile(session, "file:myfile", NULL);
session | the session handle |
name | the URI of the file to dump |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::msg_printf | ( | WT_SESSION * | session, |
const char * | fmt, | ||
... | |||
) |
Send a string to the message handler for debugging.
ret = session->msg_printf(session, "process pid %lu", mypid);
session | the session handle |
fmt | a printf-like format specification |
int WT_SESSION::open_cursor | ( | WT_SESSION * | session, |
const char * | uri, | ||
WT_CURSOR * | to_dup, | ||
const char * | config, | ||
WT_CURSOR ** | cursorp | ||
) |
Open a cursor.
Open a new cursor on the specified data source. Cursor handles should be discarded by calling WT_CURSOR::close.
Cursors are light-weight objects but may hold references to heavier-weight objects. Applications should usually not cache cursors as a performance optimization, instead, a new cursor should be opened for new groups of operations.
Cursors are opened in the context of the current transaction. The cursor must be closed before the transaction can end. If WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction are called with cursors open in the transaction, the cursor handles will be closed implicitly and must not be accessed again.
An existing cursor can be duplicated by passing it as the to_dup
parameter and setting the uri
parameter to NULL
, otherwise the to_dup
parameter should be NULL
.
ret = session->open_cursor( session, "table:mytable", NULL, NULL, &cursor);
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, be read-only or not support transactional updates). See Cursor types for more information. The following are the builtin cursor types:
| |||||||||||||||||||||||||||
to_dup | a cursor to duplicate | |||||||||||||||||||||||||||
session | the session handle | |||||||||||||||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
| |||||||||||||||||||||||||||
cursorp | a pointer to the newly opened cursor |
int WT_SESSION::rename | ( | WT_SESSION * | session, |
const char * | oldname, | ||
const char * | newname, | ||
const char * | config | ||
) |
Rename an object.
ret = session->rename(session, "table:old", "table:new", NULL);
session | the session handle |
oldname | the current URI of the object, such as "table:old" |
newname | the new name of the object, such as "table:new" |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::rollback_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Roll back the current transaction.
Not yet supported in WiredTiger.
Any cursors opened during the transaction will be closed before the rollback is processed.
Ignored if no transaction is in progress.
ret = session->rollback_transaction(session, NULL);
session | the session handle |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::salvage | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Salvage a file or table.
Salvage rebuilds the file, or files of which a table is comprised, discarding any corrupted file blocks.
Previously deleted records may re-appear, and inserted records may disappear, when salvage is done, so salvage should not be run unless it is known to be necessary. Normally, salvage should be called after a file or table has been corrupted, as reported by the WT_SESSION::verify method.
Files are rebuilt in place, the salvage method overwrites the existing files.
ret = session->salvage(session, "table:mytable", NULL);
session | the session handle | ||||||
name | the URI of the file or table to salvage | ||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::sync | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Sync a file or table.
Flush dirty pages from a table to stable storage. Note that not all pages are necessarily flushed (pages pinned in memory, or in use by other threads of control may not be written until all open session handles for the table are closed).
ret = session->sync(session, "table:mytable", NULL);
session | the session handle |
name | the URI of the file or table to sync |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::truncate | ( | WT_SESSION * | session, |
const char * | name, | ||
WT_CURSOR * | start, | ||
WT_CURSOR * | stop, | ||
const char * | config | ||
) |
Truncate a file, table or a cursor range.
ret = session->truncate(session, "table:mytable", NULL, NULL, NULL);
WT_CURSOR *start, *stop; ret = session->open_cursor( session, "table:mytable", NULL, NULL, &start); start->set_key(start, "June01"); ret = start->search(start); ret = session->open_cursor( session, "table:mytable", NULL, NULL, &stop); stop->set_key(stop, "June30"); ret = stop->search(stop); ret = session->truncate(session, NULL, start, stop, NULL);
session | the session handle |
name | the URI of the file or table to truncate |
start | optional cursor marking the first record discarded; if NULL , the truncate starts from the beginning of the table |
stop | optional cursor marking the last record discarded; if NULL , the truncate continues to the end of the table |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::upgrade | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Upgrade a file or table.
Upgrade upgrades a file, or the files of which a table is comprised.
ret = session->upgrade(session, "table:mytable", NULL);
session | the session handle |
name | the URI of the file or table to upgrade |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::verify | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Verify a file or table.
Verify reports if a file, or the files of which a table is comprised, have been corrupted. The WT_SESSION::salvage method can be used to repair a corrupted file,
ret = session->verify(session, "table:mytable", NULL);
session | the session handle |
name | the URI of the file or table to verify |
config | Configuration string, see Configuration Strings. No values currently permitted. |
The connection for this session.