From 9ba69ab7180c49c6a0f01b002a94e3a3798ec00a Mon Sep 17 00:00:00 2001 From: Susan LoVerso Date: Tue, 16 Feb 2016 15:18:43 -0500 Subject: [PATCH] WT-2349 Read-only documentation --- dist/api_data.py | 3 +- src/docs/programming.dox | 1 + src/docs/readonly.dox | 62 +++++++++++++++++++++++++++++++++++++++ src/docs/wtperf.dox | 4 +++ src/include/wiredtiger.in | 9 +++--- 5 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 src/docs/readonly.dox diff --git a/dist/api_data.py b/dist/api_data.py index 5a07440912f..1623c315710 100644 --- a/dist/api_data.py +++ b/dist/api_data.py @@ -480,7 +480,8 @@ connection_runtime_config = [ ]), Config('readonly', 'false', r''' open connection in read-only mode. The database must exist. All - methods that may modify a database are disabled.''', + methods that may modify a database are disabled. See @ref readonly + for more information''', type='boolean'), Config('shared_cache', '', r''' shared cache configuration options. A database should configure diff --git a/src/docs/programming.dox b/src/docs/programming.dox index 5d79edd660b..f717f4ed1fe 100644 --- a/src/docs/programming.dox +++ b/src/docs/programming.dox @@ -30,6 +30,7 @@ each of which is ordered by one or more columns.

Programming notes

- @subpage threads - @subpage namespace +- @subpage readonly @m_if{c} - @subpage signals @m_endif diff --git a/src/docs/readonly.dox b/src/docs/readonly.dox new file mode 100644 index 00000000000..1da103085bf --- /dev/null +++ b/src/docs/readonly.dox @@ -0,0 +1,62 @@ +/*! @m_page{{c,java},readonly,Database read-only mode} + +WiredTiger supports opening a database in read-only mode. When a database +is opened in read-only mode, all modifications are disabled on the WT_CONNECTION +handle, any sessions opened in that connection and any cursors opened on any +of those sessions. Any session handle method that modifies any part of the +database will return an error. Similarly, any WiredTiger internal threads +that perform modifications will not perform that work. + +When a database is opened in read-only mode, WiredTiger assumes the database +directory and content already exist and that it was a clean shutdown, +particularly if logging and recovery are used. + +@section readonly_config Database readonly configuration considerations + +Use of the \c readonly configuration may affect other configuration settings. +Where the default setting contradicts read-only operation, WiredTiger +overrides those defaults to perform in a non-modifying mode. For example, +merges are turned off if LSM trees are in use, and log file archiving is +disabled if logging is configured. + +Other settings where the user must explicitly turn them on return an error +if that setting contradicts read-only mode. For example, statistics logging +or zero filling log files are not allowed during read-only mode and trying +to set those will result in an error. + +@section readonly_logging Readonly configuration and logging + +If logging is enabled on the database when it is opened with the \c readonly +configuration, log file archiving and log file pre-allocation are disabled. +The log files will not be modified any way. Any pre-allocated or temporary +log files that exist from an earlier run that would normally be removed will +remain. + +@section readonly_recovery Readonly configuration and recovery + +Since recovery only reapplies modifications, clearly no recovery actions can +occur during read-only mode. The system will detect if recovery is necessary +or if it was a clean shutdown. Attempting to open the database via +::wiredtiger_open will only proceed from a clean shutdown and return an error +if any recovery is required. + +@section readonly_lsm Readonly configuration and LSM trees + +If LSM trees are in use, starting up in read-only mode turns off all +modification. Internal LSM operations such as merging, creating new chunks, +creating bloom filters and dropping old chunks are disabled. + +@section readonly_handles Readonly configuration and multiple database handles + +One unusual affect of read-only operations is the potential for multiple +read-only database handles open to the same database at the same time, in +limited circumstances. WiredTiger prevents multiple connection handles +by writing to a lock file. Even in read-only mode, creating and writing +to the lock file is attempted. In the case where the database directory or +the lock file does not exist or cannot be created or written to, a read-only +handle is allowed to proceed. So in the case where the database directory +and its files are read-only, multiple read-only connection handles could +be open at the same time. In the case where the database directory is +writable the normal file locking occurs preventing multiple connections. + +*/ diff --git a/src/docs/wtperf.dox b/src/docs/wtperf.dox index 1f0d1533ac4..6f3d2f87ee0 100644 --- a/src/docs/wtperf.dox +++ b/src/docs/wtperf.dox @@ -212,6 +212,10 @@ insert operations generate random content for the value @par read_range (unsigned int, default=0) scan a range of keys after each search +@par readonly (boolean, default=false) +reopen the connection between populate and workload phases in readonly +mode. Requires reopen_connection turned on (default). Requires that +read be the only workload specified @par reopen_connection (boolean, default=true) close and reopen the connection between populate and workload phases @par report_interval (unsigned int, default=2) diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in index 93eb2d4be8f..6c09983fead 100644 --- a/src/include/wiredtiger.in +++ b/src/include/wiredtiger.in @@ -1854,8 +1854,9 @@ struct __wt_connection { * integer between 3 and 20; default \c 4.} * @config{ ),,} * @config{readonly, open connection in read-only mode. The database - * must exist. All methods that may modify a database are disabled., a - * boolean flag; default \c false.} + * must exist. All methods that may modify a database are disabled. + * See @ref readonly for more information., a boolean flag; default \c + * false.} * @config{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 @@ -2330,8 +2331,8 @@ struct __wt_connection { * processes). Not yet supported in WiredTiger., a boolean flag; default * \c false.} * @config{readonly, open connection in read-only mode. The database must - * exist. All methods that may modify a database are disabled., a boolean flag; - * default \c false.} + * exist. All methods that may modify a database are disabled. See @ref + * readonly for more information., a boolean flag; default \c false.} * @config{session_max, maximum expected number of sessions (including server * threads)., an integer greater than or equal to 1; default \c 100.} * @config{shared_cache = (, shared cache configuration options. A database