439 lines
15 KiB
Python
439 lines
15 KiB
Python
# This file is a python script that describes the WiredTiger API.
|
|
|
|
class Error:
|
|
def __init__(self, name, desc, long_desc=None, **flags):
|
|
self.name = name
|
|
self.desc = desc
|
|
self.long_desc = long_desc
|
|
self.flags = flags
|
|
|
|
errors = [
|
|
Error('WT_DEADLOCK', 'conflict between concurrent operations', '''
|
|
This error is generated when an operation cannot be completed
|
|
due to a conflict with concurrent operations. The operation
|
|
should be retried. If a transaction is in progress, it should
|
|
be rolled back and the operation retried in a new
|
|
transaction.'''),
|
|
Error('WT_DUPLICATE_KEY', 'attempt to insert an existing key', '''
|
|
This error is generated when the application attempts to insert
|
|
a record with the same key as an existing record without the
|
|
'overwrite' configuration to WT_SESSION::open_cursor.'''),
|
|
Error('WT_ERROR', 'non-specific WiredTiger error', '''
|
|
This error is generated for cases that are not covered by
|
|
specific error returns.'''),
|
|
Error('WT_NOTFOUND', 'cursor item not found', '''
|
|
This error indicates a cursor operation did not find a
|
|
record to return. This includes search and other
|
|
operations where no record matched the cursor's search
|
|
key such as WT_CURSOR::update or WT_CURSOR::remove.'''),
|
|
Error('WT_RESTART', 'restart the operation (internal)', undoc=True),
|
|
]
|
|
|
|
class Method:
|
|
def __init__(self, config, **flags):
|
|
self.config = config
|
|
self.flags = flags
|
|
|
|
class Config:
|
|
def __init__(self, name, default, desc, **flags):
|
|
self.name = name
|
|
self.default = default
|
|
self.desc = desc
|
|
self.flags = flags
|
|
|
|
def __cmp__(self, other):
|
|
return cmp(self.name, other.name)
|
|
|
|
# All schema objects can have column names (optional for simple tables).
|
|
column_meta = [
|
|
Config('columns', '', r'''
|
|
list of the column names. Comma-separated list of the form
|
|
<code>(column[,...])</code>. For tables, the number of entries
|
|
must match the total number of values in \c key_format and \c
|
|
value_format. For colgroups and indices, all column names must
|
|
appear in the list of columns for the table''',
|
|
type='list'),
|
|
]
|
|
|
|
filename_meta = [
|
|
Config('filename', '', r'''
|
|
override the default filename derived from the object name'''),
|
|
]
|
|
|
|
format_meta = column_meta + [
|
|
Config('key_format', 'u', r'''
|
|
the format of the data packed into key items. See @ref
|
|
schema_format_types for details. By default, the key_format is
|
|
\c 'u' and applications use WT_ITEM structures to manipulate
|
|
raw byte arrays. By default, records are stored in row-store
|
|
files: keys of type \c 'r' are record numbers and records
|
|
referenced by record number are stored in column-store files''',
|
|
type='format'),
|
|
Config('value_format', 'u', r'''
|
|
the format of the data packed into value items. See @ref
|
|
schema_format_types for details. By default, the value_format
|
|
is \c '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''',
|
|
type='format'),
|
|
]
|
|
|
|
# Per-file configuration
|
|
file_config = format_meta + [
|
|
Config('allocation_size', '512B', r'''
|
|
the file unit allocation size, in bytes, must a power-of-two;
|
|
smaller values decrease the file space required by overflow
|
|
items, and the default value of 512B is a good choice absent
|
|
requirements from the operating system or storage device''',
|
|
min='512B', max='128MB'),
|
|
Config('block_compressor', '', r'''
|
|
configure a compressor for file blocks. Permitted values are
|
|
empty (off) or \c "bzip2", \c "snappy" or custom compression
|
|
engine \c "name" created with WT_CONNECTION::add_compressor.
|
|
See @ref compression for more information'''),
|
|
Config('checksum', 'true', r'''
|
|
configure file block checksums; if false, the block
|
|
manager is free to not write or check block checksums.
|
|
This can increase performance in applications where
|
|
compression provides checksum functionality or read-only
|
|
applications where blocks require no verification''',
|
|
type='boolean'),
|
|
Config('collator', '', r'''
|
|
configure custom collation for keys. Value must be a collator
|
|
name created with WT_CONNECTION::add_collator'''),
|
|
Config('huffman_key', '', r'''
|
|
configure Huffman encoding for keys. Permitted values
|
|
are empty (off), \c "english", \c "utf8<file>" or \c
|
|
"utf16<file>". See @ref huffman for more information'''),
|
|
Config('huffman_value', '', r'''
|
|
configure Huffman encoding for values. Permitted values
|
|
are empty (off), \c "english", \c "utf8<file>" or \c
|
|
"utf16<file>". See @ref huffman for more information'''),
|
|
Config('internal_key_truncate', 'true', r'''
|
|
configure internal key truncation, discarding unnecessary
|
|
trailing bytes on internal keys (ignored for custom
|
|
collators)''',
|
|
type='boolean'),
|
|
Config('internal_page_max', '2KB', r'''
|
|
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''',
|
|
min='512B', max='512MB'),
|
|
Config('internal_item_max', '0', r'''
|
|
the maximum key size stored on internal nodes, in bytes. If
|
|
zero, a maximum is calculated to permit at least 8 keys per
|
|
internal page''',
|
|
min=0),
|
|
Config('key_gap', '10', r'''
|
|
the maximum gap between instantiated keys in a Btree leaf page,
|
|
constraining the number of keys processed to instantiate a
|
|
random Btree leaf page key''',
|
|
min='0'),
|
|
Config('leaf_page_max', '1MB', r'''
|
|
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''',
|
|
min='512B', max='512MB'),
|
|
Config('leaf_item_max', '0', r'''
|
|
the maximum key or value size stored on leaf nodes, in bytes.
|
|
If zero, a size is calculated to permit at least 8 items
|
|
(values or row store keys) per leaf page''',
|
|
min=0),
|
|
Config('prefix_compression', 'true', r'''
|
|
configure row-store format key prefix compression''',
|
|
type='boolean'),
|
|
Config('split_pct', '75', r'''
|
|
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''',
|
|
min='25', max='100'),
|
|
Config('type', 'btree', r'''
|
|
the file type''',
|
|
choices=['btree']),
|
|
]
|
|
|
|
# File metadata, including both configurable and non-configurable (internal)
|
|
file_meta = file_config + [
|
|
Config('snapshot', '', r'''
|
|
the file snapshot entries'''),
|
|
Config('version', '(major=0,minor=0)', r'''
|
|
the file version'''),
|
|
]
|
|
|
|
table_only_meta = [
|
|
Config('colgroups', '', r'''
|
|
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''', type='list'),
|
|
]
|
|
|
|
colgroup_meta = column_meta + filename_meta
|
|
|
|
index_meta = column_meta + filename_meta
|
|
|
|
table_meta = format_meta + table_only_meta
|
|
|
|
methods = {
|
|
'file.meta' : Method(file_meta),
|
|
|
|
'colgroup.meta' : Method(colgroup_meta),
|
|
|
|
'index.meta' : Method(index_meta),
|
|
|
|
'table.meta' : Method(table_meta),
|
|
|
|
'cursor.close' : Method([
|
|
]),
|
|
|
|
'session.close' : Method([]),
|
|
|
|
'session.create' : Method(table_meta + file_config + filename_meta + [
|
|
Config('exclusive', 'false', r'''
|
|
fail if the object exists. When false (the default), if the
|
|
object exists, check that its settings match the specified
|
|
configuration''',
|
|
type='boolean'),
|
|
]),
|
|
|
|
'session.drop' : Method([
|
|
Config('force', 'false', r'''
|
|
return success if the object does not exist''',
|
|
type='boolean'),
|
|
Config('snapshot', '', r'''
|
|
specify one or more snapshots to drop.
|
|
|
|
The value must be either the name of a single snapshot to drop
|
|
(a string), or a list containing one of the following keys:
|
|
\c "all" to drop all snapshots,
|
|
\c "from=<snapshot>" to drop all snapshots after and including
|
|
the named snapshots, or
|
|
\c "to=<snapshot>" to drop all snapshots before and including
|
|
the named snapshot'''),
|
|
]),
|
|
|
|
'session.dumpfile' : Method([]),
|
|
'session.log_printf' : Method([]),
|
|
|
|
'session.open_cursor' : Method([
|
|
Config('append', 'false', r'''
|
|
only supported by cursors with record number keys: append the
|
|
value as a new record, creating a new record number key''',
|
|
type='boolean'),
|
|
Config('bulk', 'false', r'''
|
|
configure the cursor for bulk loads; bulk-load is a fast
|
|
load path for empty objects, only empty objects may be
|
|
bulk-loaded''',
|
|
type='boolean'),
|
|
Config('dump', '', r'''
|
|
configure the cursor for dump format inputs and outputs:
|
|
"hex" selects a simple hexadecimal format, "print"
|
|
selects a format where only non-printing characters are
|
|
hexadecimal encoded. The cursor dump format is compatible
|
|
with the @ref utility_dump and @ref utility_load commands''',
|
|
choices=['hex', 'print']),
|
|
Config('isolation', 'read-committed', r'''
|
|
the isolation level for this cursor, ignored for transactional
|
|
cursors''',
|
|
choices=['snapshot', 'read-committed', 'read-uncommitted']),
|
|
Config('overwrite', 'false', r'''
|
|
change the behavior of the cursor's insert method to
|
|
overwrite previously existing values''',
|
|
type='boolean'),
|
|
Config('raw', 'false', r'''
|
|
ignore the encodings for the key and value, manage data as if
|
|
the formats were \c "u". See @ref cursor_raw for details''',
|
|
type='boolean'),
|
|
Config('snapshot', '', r'''
|
|
the name of a snapshot to open'''),
|
|
Config('statistics', 'false', r'''
|
|
configure the cursor for statistics''',
|
|
type='boolean'),
|
|
Config('statistics_clear', 'false', r'''
|
|
statistics cursors only; reset statistics counters when the
|
|
cursor is closed''',
|
|
type='boolean'),
|
|
]),
|
|
|
|
'session.rename' : Method([]),
|
|
'session.salvage' : Method([
|
|
Config('force', 'false', r'''
|
|
force salvage even of files that do not appear to be WiredTiger
|
|
files''',
|
|
type='boolean'),
|
|
]),
|
|
'session.sync' : Method([
|
|
Config('snapshot', '', r'''
|
|
if non-empty, create a named snapshot'''),
|
|
]),
|
|
'session.truncate' : Method([]),
|
|
'session.upgrade' : Method([]),
|
|
'session.verify' : Method([]),
|
|
|
|
'session.begin_transaction' : Method([
|
|
Config('isolation', 'snapshot', r'''
|
|
the isolation level for this transaction''',
|
|
choices=['read-uncommitted', 'snapshot']),
|
|
Config('name', '', r'''
|
|
name of the transaction for tracing and debugging'''),
|
|
Config('sync', 'full', r'''
|
|
how to sync log records when the transaction commits''',
|
|
choices=['full', 'flush', 'write', 'none']),
|
|
Config('priority', 0, r'''
|
|
priority of the transaction for resolving conflicts.
|
|
Transactions with higher values are less likely to abort''',
|
|
min='-100', max='100'),
|
|
]),
|
|
|
|
'session.commit_transaction' : Method([]),
|
|
'session.rollback_transaction' : Method([]),
|
|
|
|
'session.checkpoint' : Method([
|
|
Config('snapshot', '', r'''
|
|
if non-empty, create named snapshots in files'''),
|
|
]),
|
|
|
|
'connection.add_collator' : Method([]),
|
|
'connection.add_compressor' : Method([]),
|
|
'connection.add_data_source' : Method([]),
|
|
'connection.add_extractor' : Method([]),
|
|
'connection.close' : Method([]),
|
|
|
|
'connection.load_extension' : Method([
|
|
Config('entry', 'wiredtiger_extension_init', r'''
|
|
the entry point of the extension'''),
|
|
Config('prefix', '', r'''
|
|
a prefix for all names registered by this extension (e.g., to
|
|
make namespaces distinct or during upgrades'''),
|
|
]),
|
|
|
|
'connection.open_session' : Method([]),
|
|
|
|
'wiredtiger_open' : Method([
|
|
Config('buffer_alignment', '-1', r'''
|
|
in-memory alignment (in bytes) for buffers used for I/O. By
|
|
default, a platform-specific alignment value is used (512 bytes
|
|
on Linux systems, zero elsewhere)''',
|
|
min='-1', max='1MB'),
|
|
Config('cache_size', '100MB', r'''
|
|
maximum heap memory to allocate for the cache''',
|
|
min='1MB', max='10TB'),
|
|
Config('create', 'false', r'''
|
|
create the database if it does not exist''',
|
|
type='boolean'),
|
|
Config('direct_io', '', r'''
|
|
Use \c O_DIRECT to access files. Options are given as a
|
|
list, such as <code>"direct_io=[data]"</code>''',
|
|
type='list', choices=['data', 'log']),
|
|
Config('home_environment', 'false', r'''
|
|
use the \c WIREDTIGER_HOME environment variable for naming
|
|
unless the process is running with special privileges.
|
|
See @ref home for more information''',
|
|
type='boolean'),
|
|
Config('home_environment_priv', 'false', r'''
|
|
use the \c WIREDTIGER_HOME environment variable for naming
|
|
regardless of whether or not the process is running with
|
|
special privileges. See @ref home for more information''',
|
|
type='boolean'),
|
|
Config('extensions', '', r'''
|
|
list of extensions to load. Optional values are passed as the
|
|
\c config parameter to WT_CONNECTION::load_extension. Complex
|
|
paths may need quoting, for example,
|
|
<code>extensions=("/path/to/ext.so"="entry=my_entry")</code>''',
|
|
type='list'),
|
|
Config('error_prefix', '', r'''
|
|
prefix string for error messages'''),
|
|
Config('eviction_target', '80', r'''
|
|
continue evicting until the cache becomes less full than this
|
|
(as a percentage). Must be less than \c eviction_trigger''',
|
|
min=10, max=99),
|
|
Config('eviction_trigger', '95', r'''
|
|
trigger eviction when the cache becomes this full (as a
|
|
percentage)''',
|
|
min=10, max=99),
|
|
Config('hazard_max', '30', r'''
|
|
number of simultaneous hazard references per session handle''',
|
|
min='15'),
|
|
Config('logging', 'false', r'''
|
|
enable logging''',
|
|
type='boolean'),
|
|
Config('multiprocess', 'false', r'''
|
|
permit sharing between processes (will automatically start an
|
|
RPC server for primary processes and use RPC for secondary
|
|
processes). <b>Not yet supported in WiredTiger</b>''',
|
|
type='boolean'),
|
|
Config('session_max', '50', r'''
|
|
maximum expected number of sessions (including server
|
|
threads)''',
|
|
min='1'),
|
|
Config('sync', 'true', r'''
|
|
sync files when closing or writing snapshots''',
|
|
type='boolean'),
|
|
Config('transactional', 'true', r'''
|
|
support transactional semantics''',
|
|
type='boolean'),
|
|
Config('verbose', '', r'''
|
|
enable messages for various events. Options are given as a
|
|
list, such as <code>"verbose=[evictserver,read]"</code>''',
|
|
type='list', choices=[
|
|
'block',
|
|
'evict',
|
|
'evictserver',
|
|
'fileops',
|
|
'hazard',
|
|
'mutex',
|
|
'read',
|
|
'readserver',
|
|
'reconcile',
|
|
'salvage',
|
|
'snapshot',
|
|
'verify',
|
|
'write']),
|
|
]),
|
|
}
|
|
|
|
flags = {
|
|
###################################################
|
|
# Internal routine flag declarations
|
|
###################################################
|
|
'direct_io' : [ 'DIRECTIO_DATA', 'DIRECTIO_LOG' ],
|
|
'page_free' : [ 'PAGE_FREE_IGNORE_DISK' ],
|
|
'rec_evict' : [ 'REC_SINGLE' ],
|
|
'verbose' : [
|
|
'VERB_block',
|
|
'VERB_evict',
|
|
'VERB_evictserver',
|
|
'VERB_fileops',
|
|
'VERB_hazard',
|
|
'VERB_mutex',
|
|
'VERB_read',
|
|
'VERB_readserver',
|
|
'VERB_reconcile',
|
|
'VERB_salvage',
|
|
'VERB_snapshot',
|
|
'VERB_verify',
|
|
'VERB_write'
|
|
],
|
|
|
|
###################################################
|
|
# Structure flag declarations
|
|
###################################################
|
|
'conn' : [
|
|
'CONN_NOSYNC',
|
|
'CONN_TRANSACTIONAL',
|
|
'SERVER_RUN'
|
|
],
|
|
'session' : [
|
|
'SESSION_HAS_CONNLOCK',
|
|
'SESSION_INTERNAL',
|
|
'SESSION_SALVAGE_QUIET_ERR'
|
|
],
|
|
}
|