diff options
Diffstat (limited to 'src/third_party/wiredtiger/src/docs/upgrading.dox')
| -rw-r--r-- | src/third_party/wiredtiger/src/docs/upgrading.dox | 952 |
1 files changed, 952 insertions, 0 deletions
diff --git a/src/third_party/wiredtiger/src/docs/upgrading.dox b/src/third_party/wiredtiger/src/docs/upgrading.dox new file mode 100644 index 00000000000..e0239919f0b --- /dev/null +++ b/src/third_party/wiredtiger/src/docs/upgrading.dox @@ -0,0 +1,952 @@ +/*! @page upgrading Upgrading WiredTiger applications + +@section version_271 Upgrading to Version 2.7.1 +<dl> +<dt>Column-store bulk-load cursors</dt> +<dd> +Historically, bulk-load of a column-store object ignored any key set in +the cursor and automatically assigned each inserted row the next +sequential record number for its key. In the 2.7.1 release, column-store +objects match row-store behavior and require the cursor key be set +before an insert. (This also allows allows sparse tables to be created +in column-store objects, any skipped records are created as +already-deleted rows.) To match the previous behavior, specify the +\c append configuration string when opening the column-store bulk-load +cursor; this causes the cursor's key to be ignored and each inserted row +will be assigned the next record number. +</dd> + +<dt>Change to WT_SESSION::truncate with URI</dt> +<dd> +If using the WT_SESSION::truncate API with a file: URI for a full table +truncate, underlying algorithmic changes result in some visible differences. +This call can now return WT_ROLLBACK. Applications should be prepared to +handle this error. This method no longer requires exclusive access to the +table. Also the underlying disk space may not be immediately +reclaimed when the call returns. The performance of this API may differ +from earlier releases. +</dd> + +</dl><hr> +@section version_270 Upgrading to Version 2.7.0 + +<dl> +<dt>Change to config_base=false</dt> +<dd> +If \c config_base=false in the config passed directly to ::wiredtiger_open, +any existing base configuration file will now be ignored. If an application +was relying on this behavior, a connection will be opened with different +settings after upgrading, which could lead to errors or unexpected behavior. +</dd> + +<dt>Statistic change</dt> +<dd> +The statistic "pages split during eviction" was replaced. It has been +replaced by a pair of statistics "internal pages split during eviction" and +"leaf pages split during eviction". +</dd> + +<dt>Change to WT_CURSOR::insert</dt> +<dd> +The WT_CURSOR::insert method in this release has slightly different semantics +with respect to referencing application memory. In previous releases, +WT_CURSOR::insert continued to reference application-memory specified to +either WT_CURSOR::set_key or WT_CURSOR::set_value after a successful return, +which could potentially lead to a core dump if the application freed that +memory before a subsequent call to a WT_CURSOR:: method without an intermediate +WT_CURSOR::set_key or WT_CURSOR::set_value call. In the 2.7.0 release, +WT_CURSOR::insert behaves like the other cursor methods and does not reference +application memory after a successful return. Applications depending on the +previous semantic will require modifications to set the cursor's key and/or +value after a successful WT_CURSOR::insert call. +</dd> + +<dt>WT_SESSION.verify</dt> +<dd> +The WT_SESSION.verify method in this release has a new configuration +option, \c strict. By default, with \c strict set to \c false, +WT_SESSION.verify will no longer return an error for problems that do +not impact the future use of the object (for example, if a leaked block +were detected, the application can continue to run). WT_SESSION.verify +will continue to output an error message whenever an error is detected, +only the final return value is affected. This change allows +applications to verify objects and continue if at all possible. +Applications in development should configure \c strict to \c true in +order to terminate the application whenever an error is detected. +</dd> + +</dl><hr> +@section version_261 Upgrading to Version 2.6.1 + +<dl> +<dt>Move the per transaction sync configuration</dt> +<dd> +Move the sync configuration setting from WT_SESSION::begin_transaction to +WT_SESSION::commit_transaction. Change the configuration from a boolean to a +string with options of on, off, background. Deprecated support for specifying +the configuration to WT_SESSION::begin_transaction is maintained for now. +</dd> + +</dl><hr> +@section version_260 Upgrading to Version 2.6.0 + +<dl> +<dt>LZ4 compression</dt> +<dd> +The LZ4 compression support has been updated in this release in non-backward +compatible ways; <b>tables and files compressed using LZ4 compression with +WiredTiger 2.5.3 must be dumped then re-loaded using WiredTiger 2.6.0.</b> +</dd> + +<dt>wiredtiger_open file manager configuration changes</dt> +<dd> +The configuration settings related to file handle management have changed +significantly in this release. If your application uses the file_manager +configuration setting, please refer to the API documentation for the latest +settings. +</dd> + +<dt>Statistic change</dt> +<dd> +The statistic "log read operations" was removed. The function that +used that statistic was never called inside WiredTiger and was also +removed. +</dd> + +<dt>File handle closing</dt> +<dd> +In WiredTiger, a separate thread of control periodically reviews open +objects, closing ones which have been idle for some period of time and +discarding them from the cache. In previous WiredTiger releases, this +review was independent of the number of open file handles. In this +release, WiredTiger only reviews the file handles if at least 250 file +handles are open. How often file handles are reviewed (the default is +30 seconds), and how many file handles must be opened before review is +triggered, can be configured using the \c file_manager configuration +values to the ::wiredtiger_open call. +</dd> + +<dt>Table drop changes</dt> +<dd> +There has been a functionality change to the WT_SESSION::drop API when the +\c force configuration option is included. The table is now dropped in the +background and does not flush data from cache. +</dd> + +</dl><hr> +@section version_253 Upgrading to Version 2.5.3 +<dl> + +<dt>Configuration string case-sensitivity</dt> +<dd> +In previous WiredTiger releases, there were several cases where configuration +strings were treated in a case-sensitive manner (for example, it was possible +to specify "True", "true" or even "tRuE" as a boolean value). For consistency, +in this release all WiredTiger configuration strings are case-sensitive, and +only "true" will be accepted. +</dd> + +<dt>Statistics cursor refresh</dt> +<dd> +In previous releases of WiredTiger, a statistics cursor made a snapshot +of the relevant statistics before the first statistics value was read, +and those values remained unchanged from that point on, no matter how +the cursor was used. In the WiredTiger 2.5.2 release, calling the +WT_CURSOR::reset method to reset the cursor refreshes the statistics +returned by the cursor. +</dd> + +<dt>Buffer alignment on Linux</dt> +<dd> +In previous releases of WiredTiger, all buffers used for I/O were aligned +to 4KB boundaries by default. In the WiredTiger 2.5.2 release, alignment +is only enforced when direct I/O is configured. +</dd> + +</dl><hr> +@section version_252 Upgrading to Version 2.5.2 + +There are no special upgrade steps required. + +@section version_251 Upgrading to Version 2.5.1 +<dl> + +<dt>Statistics cursors on data sources</dt> +<dd> +Opening a statistics cursor on a data source without a \c checkpoint name +no longer aggregates statistics for all open checkpoints on that data +source. The returned statistics will only be for the in-memory version of +the data source. + +For applications that read and write from ordinary tables (without +specifying a \c checkpoint), there will be no change. Applications that +opened cursors on checkpoints and relied on their statistics being +aggregated into a single statistics cursor will need to open statistics +cursors on each checkpoint. +</dd> + +</dl><hr> +@section version_250 Upgrading to Version 2.5.0 +<dl> + +<dt>WT_STAT_CONN_LOG_BYTES_USER renamed WT_STAT_CONN_LOG_BYTES_PAYLOAD</dt> +<dd> +The statistic for the number of bytes written to the log minus the overhead of +log record headers and padding was renamed to make the intent clearer. Any +applications using the old name will need to be updated. +</dd> + +<dt>"none" configuration for collators, compressors and extractors</dt> +<dd> +Collators, compressors and extractors can now be disabled with an explicit +\c "none" value as an alternative to using an empty string. Any applications +using the name \c "none" for a collator, compressor or extractor will need to +be updated. +</dd> + +<dt>maximum keys and value sizes +<dd> +The WT_SESSION::create \c internal_item_max and \c leaf_item_max +configuration strings are now deprecated in favor of the +\c internal_key_max, \c leaf_key_max, and \c leaf_value_max +configuration strings. See @ref tune_page_sizes for more information. +</dd> + +</dl><hr> +@section version_241 Upgrading to Version 2.4.1 +<dl> + +<dt>WT_DEADLOCK renamed</dt> +<dd> +The \c WT_DEADLOCK error return has been deprecated in favor of ::WT_ROLLBACK +to clarify that WT_SESSION::rollback_transaction should be called; no program +changes are required. +</dd> +<dt>Statistics keys changed</dt> +<dd> +The names of WiredTiger statistics have been updated to be more consistently +named, and simpler to categorize. Any application that was parsing the +strings output by statistics will need to be updated. +</dd> + +</dl><hr> +@section version_240 Upgrading to Version 2.4.0 +<dl> + +<dt>Default configuration file changes</dt> +<dd> +WiredTiger creates a configuration file when a database is first created. This +release adds a version number to that configuration file, and functionality +to automatically translate configuration settings between versions moving +forward. +</dd> +<dt>Cursors no longer reset on transaction begin or commit</dt> +<dd> +In previous versions of WiredTiger, all cursors in a session were reset at +transaction boundaries (WT_SESSION::begin_transaction, +WT_SESSION::commit_transaction and WT_SESSION::rollback_transaction). +Now they are only reset by WT_SESSION::rollback_transaction. + +This change means that a cursor can be used to iterate through a table and +perform transactional updates based on the visited records without the cursor +losing its position. + +Applications relying on this behavior (for example, to avoid pinning the +underlying cursor resources), should reset cursors explicitly when the +position is no longer required. +</dd> + +<dt>WT_COLLATOR interface changes</dt> +<dd> +Add a new WT_COLLATOR::customize callback that WiredTiger will call (if set) +for each data source configured to use the collator. Applications using the +existing WT_COLLATOR interface that do not require the new functionality should +set this callback to \c NULL. +</dd> +<dt>::wiredtiger_open lsm_merge option changed</dt> +<dd> +The global lsm_merge configuration setting has been moved into +the \c lsm_manager option group. To disable merges in all LSM +trees pass \c lsm_manger=(merge=false) to ::wiredtiger_open. +</dd> +<dt>Java include path search changes</dt> +<dd> +We have updated the configure logic used to search for Java Native Interface +files. This fixes problems building WiredTiger's Java API, particularly on +OS X, but may introduce problems if your build procedure relied on the old +search behavior. +</dd> +<dt>Default mutex implementation changed</dt> +<dd> +The default mutex implementation has been changed from adaptive pthread +mutexes to non-adaptive pthread mutexes. Installations can explicitly +select adaptive pthread mutexes by specifying +\c --with-spinlock=pthread_adaptive at configuration time. +</dd> +<dt>LSM merge threads option change</dt> +<dd> +The WT_SESSION::create \c lsm=(merge_threads) configuration option has been +replaced by the W::wiredtiger_open \c lsm_manager=(worker_thread_max) option. +The new version specifies a set of LSM threads that are shared across all +LSM trees in a database, the older configuration was per LSM table. +</dd> + +</dl><hr> +@section version_231 Upgrading to Version 2.3.1 +<dl> + +<dt>::wiredtiger_open eviction_workers configuration changed</dt> +<dd> +The \c eviction_workers configuration setting has been replaced by +\c eviction=(threads_min) and \c eviction=(threads_max) settings. + +There is also a semantic change because \c eviction_workers used to +configure additional threads whereas the new settings configure the total +number of threads involved with eviction. +</dd> + +</dl><hr> +@section version_230 Upgrading to Version 2.3.0 + +There are no special upgrade steps required. + +@section version_221 Upgrading to Version 2.2.1 +<dl> + +<dt>::wiredtiger_open configuration parsing order changed</dt> +<dd> +In the 2.2.1 release, the order that configuration strings are +parsed and override earlier values changed. Applications using +the \c Wiredtiger.config file or \c WIREDTIGER_CONFIG environment +variable may need to change. The old order: +<ol> +<li> default ::wiredtiger_open configuration</li> +<li> base configuration file, created with the database</li> +<li> user configuration file \c Wiredtiger.config</li> +<li> user environment variable \c WIREDTIGER_CONFIG</li> +<li> configuration string passed in to ::wiredtiger_open</li> +</ol> +<p>In the new order the user's configuration settings override:</p> +<ol> +<li> default ::wiredtiger_open configuration</li> +<li> base configuration file, created with the database</li> +<li> configuration string passed in to ::wiredtiger_open</li> +<li> user configuration file \c Wiredtiger.config</li> +<li> user environment variable \c WIREDTIGER_CONFIG</li> +</ol> + +</dd> +<dt>\c os_cache_dirty_max off for LSM</dt> +<dd> +In some earlier versions of WiredTiger, creating an LSM table automatically +configured \c os_cache_dirty_max, causing additional system calls that slowed +some workloads. Applications that benefit from this setting should set it +explicitly in WT_SESSION::create. +</dd> + +<dt>\c transaction_sync setting change</dt> +<dd> +In the 2.2.1 release of WiredTiger the ::wiredtiger_open \c transaction_sync +configuration setting has changed from a string value to a structure with two +fields: \c method, which corresponds to the previous value (\c dsync, \c fsync +or \c none), and \c enabled, which determines whether there is a sync on +every transaction commit by default. Applications can enable or disable sync +for a specific transaction with the \c sync setting to +WT_SESSION::begin_transaction. +</dd> + +</dl><hr> +@section version_220 Upgrading to Version 2.2.0 +<dl> + +<dt>WT_SESSION::create prefix_compression disabled by default</dt> +<dd> +In the 2.2.0 release, prefix compression default to \c false. Applications +that benefit from prefix compression will need to explicitly set +\c prefix_compression=true when creating tables. +</dd> + +<dt>wiredtiger_open verbose message changes</dt> +<dd> +In the 2.2.0 release it is now necessary to include \c --enable-verbose +in the configure command to be able to use verbose messages. +</dd> + +</dl><hr> +@section version_212 Upgrading to Version 2.1.2 +<dl> + +<dt>::wiredtiger_open shared_cache configuration changes</dt> +<dd> +In the 2.1.2 release of WiredTiger the ::wiredtiger_open \c shared_cache +configuration option group have changed. The option that was named \c enable is +no longer available. To enable a \c shared_cache it is compulsory to name +the pool being shared. +We are now also enforcing that only one of \c cache_size and \c shared_cache +are specified in the ::wiredtiger_open configuration string. +</dd> + +</dl><hr> +@section version_211 Upgrading to Version 2.1.1 +<dl> + +<dt>WT_EXTENSION_API::config methods</dt> +<dd> +In the 2.1.1 release of WiredTiger the configuration string parsing API +has been changed and added to a new public handle. The +WT_EXTENSION_API::config_strget, WT_EXTENSION_API::config_scan_begin, +WT_EXTENSION_API::config_scan_next and WT_EXTENSION_API::config_scan_end +have been removed. They have been replaced by a +WT_EXTENSION_API::config_parser_open method, which can be used to parse +configuration strings. See the WT_CONFIG_PARSER documentation for +examples on how to use the updated API. +</dd> + +</dl><hr> +@section version_21 Upgrading to Version 2.1 +<dl> + +<dt>WT_ITEM::size type</dt> +<dd> +In the 2.1 release of WiredTiger WT_ITEM::size type has changed from +\c uint32_t to \c size_t. Applications may require modifications to +resolve compile-time errors. +</dd> + +<dt>WT_COMPRESSOR::compress_raw signature</dt> +<dd> +In the 2.1 release of WiredTiger, the behavior of the compress_raw +callback has changed so that it will only be retried if it returns +\c EAGAIN. If it returns zero and sets \c result_slots to zero, +WiredTiger will assume that raw compression has failed and will fall +back to calling WT_COMPRESSOR::compress. +</dd> + +<dt>Transaction sync default setting</dt> +<dd> +In the 2.1 release of WiredTiger the ::wiredtiger_open \c transaction_sync +configuration setting default value has changed from "dsync" to "fsync". +This is due to enhancements to the group commit implementation in +WiredTiger - which mean that greater throughput can be achieved with +explicit "fsync" calls than by enabling "dsync" on a file handle. +Applications that don't execute concurrent transactions may see better +throughput with transaction_sync set to "dsync". +</dd> + +</dl><hr> +@section version_20 Upgrading to Version 2.0 +<dl> + +<dt>File format changes</dt> +<dd> +The underlying file format is unchanged in 2.0 +</dd> + +<dt>WT_SESSION::create LSM configuration options</dt> +<dd> +In the 2.0 release of WiredTiger the LSM configuration options have been +collected into a configuration option subgroup. All configuration options +to WT_SESSION::create that previously had a prefix of \c lsm_ now belong to +the \c lsm configuration group. If you are explicitly configuring any of the +following options, you should review the WT_SESSION::create documentation for +details of the updated syntax: lsm_auto_throttle, lsm_bloom, lsm_bloom_config, +lsm_bloom_bit_count, lsm_bloom_hash_count, lsm_bloom_oldest, lsm_chunk_max, +lsm_chunk_size, lsm_merge_max and lsm_merge_threads. +</dd> + +</dl><hr> +@section version_166 Upgrading to Version 1.6.6 +<dl> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.6.6 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +<dt>WT_SESSION::compact trigger configuration</dt> +<dd> +In previous releases, the \c trigger configuration string to the +WT_SESSION::compact method specified a requirement to initiate compaction; in +the 1.6.6 release, this configuration string has been removed, and compaction +will be attempted if it seems likely at least 10% of the file can be recovered. +Applications may require modifications to resolve run-time errors. +</dd> + +<dt>Statistics configuration</dt> +<dd> +In previous releases, the ::wiredtiger_open function took a \c statistics +configuration, which defaulted to false; when set to true, additional, +generally performance-expensive statistics were maintained by the +database, above and beyond a default set of statistics. In version +1.6.6, the \c statistics configuration is a list which may be set to +"all", "fast" or "none". When set to "none", no statistics are +maintained by the database; when set to "fast", only relatively +performance-inexpensive statistics are maintained, and when set to +"all", all statistics are maintained, regardless of cost. + +In previous releases, the ::wiredtiger_open function took a \c statistics_log +configuration which logged the performance-inexpensive database +statistics to a file. In version 1.6.6, the \c statistics_log +configuration logs whatever statistics are configured for the database. +If the database is configured with \c statistics to "none", no +statistics will be logged to the file; if the database is configured +with "all" or "fast", the corresponding statistics will be logged to the +file. + +In previous releases, the WT_SESSION::cursor method took +\c statistics_clear and a \c statistics_fast configurations. The +\c statistics_clear configuration defaulted to false; when set to true, +statistics counters were reset after they were gathered by the cursor. +The \c statistics_fast configuration defaulted to true; when set to +true, the cursor only gathered performance-inexpensive statistics for +the cursor, and when set to false, the cursor gathered all available +statistics, regardless of cost. + +In version 1.6.6, these two configuration booleans have been replaced +with a new configuration list \c statistics, which may be set from the +values "clear", "fast" and "all". When "fast" is configured, only +relatively performance-inexpensive statistics are gathered, and when +"all" is configured, all statistics are gathered, regardless of cost. +When "clear" is configured, statistics counters are reset after they are +gathered. + +Additionally, in version 1.6.6, statistics cursors must be configured +to agree with the database statistics configuration; when the database +statistics are configured to "none", attempts to open a statistics +cursor will fail; when the database statistics are configured to "fast", +a statistics cursor must also be configured to "fast"; when the database +statistics are configured to "all", a statistics cursor may be +configured to either "fast" or "all". Opening a statistics cursor +without configuring either "fast" or "all" will configure the cursor to +be the same as the current database configuration. + +Applications may require modifications to resolve run-time errors; +application statistics configuration and cursors should be reviewed to +confirm they are configured for the desired behavior; +</dd> + +<dt>WT_EVENT_HANDLER interface changes</dt> +<dd> +Add a new WT_EVENT_HANDLER::handle_close callback that WiredTiger will call +any time it automatically closes an application session or cursor handle. + +Additionally add a WT_SESSION parameter into the existing +WT_EVENT_HANDLER::handle_error, WT_EVENT_HANDLER::handle_message and +WT_EVENT_HANDLER::handle_progress callback functions. +</dd> + +</dl><hr> +@section version_165 Upgrading to Version 1.6.5 +<dl> + +<dt>WT_CURSOR::insert behavior</dt> +<dd> +In previous releases, the WT_CURSOR::insert ended positioned at the inserted +record. To minimize the cursor resources held by applications inserting many +records, the WT_CURSOR::insert method has been changed to end without any +position. Application insert cursors should be reviewed to confirm they do +not attempt to iterate after an insert. +</dd> + +<dt>WT_SESSION::open_cursor statistics_fast configuration</dt> +<dd> +In previous releases, the default \c statistics_fast configuration to +the WT_SESSION::open_cursor method was \c false; in the 1.6.5 release, +the default statistics_fast configuration is \c true. Applications +opening statistics cursors should be reviewed to confirm they have the +correct behavior. +</dd> + +<dt>Synchronous checkpoint configuration</dt> +<dd> +The \c sync configuration key to ::wiredtiger_open has been renamed \c checkpoint_sync. +</dd> + +</dl><hr> +@section version_164 Upgrading to Version 1.6.4 +<dl> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.6.4 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +<dt>wt utility load command</dt> +<dd> +The default behavior of the \c wt utility's \c load command has been +changed to overwrite existing data, by default, and the \c -o flag to +the \c load command (overwrite existing data) has been replaced with the +\c -n flag (do not overwrite existing data). Applications requiring +the previous default behavior of not overwriting existing data should +add the \c -n option to their command line configuration; applications +previously using the \c -o option on their command line configurations +should remove it. +</dd> + +</dl><hr> +@section version_163 Upgrading to Version 1.6.3 +<dl> + +<dt>Cursor overwrite configuration</dt> +<dd> +In previous releases, the WT_SESSION::open_cursor \c overwrite configuration +string behaved inconsistently across Btree and LSM data sources. In Btree, +\c overwrite was \c false by default and was limited to the WT_CURSOR::insert +method, changing an insert to succeed regardless of whether or not the record +previously existed. In LSM trees, \c overwrite was \c true by default, and +applied to the WT_CURSOR::insert, WT_CURSOR::remove and WT_CURSOR::update +methods, configuring all three methods to ignore the existing state of the +record. + +In the 1.6.3 release, the \c overwrite configuration is consistent across both +Btree and LSM tree data sources. For performance reasons, the default is the +behavior previously described for LSM trees: in other words, \c overwrite is +\c true by default, causing WT_CURSOR::insert, WT_CURSOR::remove and +WT_CURSOR::update to ignore the current state of the record, and these methods +will succeed regardless of whether or not the record previously exists. When +an application configures \c overwrite to \c false, WT_CURSOR::insert will fail +with ::WT_DUPLICATE_KEY if the record previously exists, and WT_CURSOR::update +and WT_CURSOR::remove will fail with ::WT_NOTFOUND if the record does not +previously exist. + +<b>This is a potentially serious API change that will not be detected by +compilation.</b> Application cursors should be reviewed to confirm they are +configured for the desired behavior. +</dd> + +<dt>::wiredtiger_open no longer accepts a \c transactional configuration</dt> +<dd> +The \c transactional configuration key has been removed from +::wiredtiger_open. Any application setting it should simply remove it, +no change in application behavior is needed. +</dd> + +</dl><hr> +@section version_162 Upgrading to Version 1.6.2 +<dl> + +<dt>Table of WiredTiger extension methods</dt> +<dd> +New functionality was added to the list of WiredTiger extension methods; +applications using the extension methods will require recompilation. +</dd> + +<dt>WT_SESSION::create no longer accepts a "source" configuration</dt> +<dd> +The \c "source" configuration key has been removed from WT_SESSION::create. +Normal applications should not have been using it, and there were a number of +bugs associated with it. +</dd> + +<dt>Default checksum configuration</dt> +<dd> +The default file checksum configuration was changed to \c uncompressed, +which means blocks that are compressed will no longer also include a +checksum, by default. Applications using compression insufficient for +the purposes of corrupted block identification should change their file +checksum configuration to \c on. +</dd> + +</dl><hr> +@section version_161 Upgrading to Version 1.6.1 +<dl> + +<dt>Default page sizes</dt> +<dd> +In the 1.6.1 release, the default for the WT_SESSION::create configuration +string \c allocation_size changed from 512B to 4KB, and the default for the +configuration string \c internal_page_max changed from 2KB to 4KB. +Applications wanting to create files with smaller allocation or internal +page sizes will need to set those configuration values explicitly. +</dd> + +<dt>Shared cache configuration</dt> +<dd> +In the 1.6.1 release, an explicit shared_cache=(enable=boolean) option was +added to the wiredtiger_open configuration options. Existing applications that +use shared cache functionality will need to add the enable option to the +configuration string. The default value for the option is false. +</dd> + +<dt>WT_COMPRESSOR::compress_raw signature</dt> +<dd> +In the 1.6.1 release, the \c split_pct argument to the +WT_COMPRESSOR::compress_raw function changed type from \c u_int to \c int, +applications may require modification to avoid compiler warnings. +</dd> + +</dl><hr> +@section version_160 Upgrading to Version 1.6.0 +<dl> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.6.0 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +</dl><hr> +@section version_153 Upgrading to Version 1.5.3 +<dl> + +<dt>Configuration strings</dt> +<dd> +An undocumented feature where configuration string case was ignored has +been removed, and all configuration strings are now case-dependent. +Applications may require modifications to resolve run-time errors. +</dd> + +<dt>Loading extensions and WT_EXTENSION_API</dt> +<dd> +The following changes are only applicable to applications loading +extensions and/or using the WiredTiger extension functions described in +WT_EXTENSION_API. + +<ul> +<li> +The signature of ::wiredtiger_extension_init has changed +from <code>(WT_SESSION *session, WT_EXTENSION_API *api)</code> to +<code>(WT_CONNECTION *connection)</code>. As no WT_EXTENSION_API +handle reference is passed to the function, the +WT_CONNECTION::get_extension_api has been added to support retrieval of +the extension API. Applications may require modifications. + +<li> +The type of all configuration arguments to extension methods has changed +from \c "const char *" to \c "WT_CONFIG_ARG *", and the WT_EXTENSION::config +method added to support configuration parsing; applications may require +modifications. + +<li> +The undocumented \c wiredtiger_XXX defines for WT_EXTENSION_API extension +methods have been removed from the \c wiredtiger_ext.h include file; +applications should instead use the method handles referenced by the +WT_EXTENSION_API handle to call extension functions. + +<li> +The extension API methods have all changed to require an additional +parameter, the WT_EXTENSION_API method handle; applications may require +modifications. + +<li> +The WT_SESSION::msg_printf method was replaced by WT_EXTENSION_API::msg_printf; +applications may require modifications. +</ul> +</dd> + +<dt>WT_DATA_SOURCE</dt> +<dd> +The following changes are only applicable to applications providing new +implementations of the WiredTiger WT_DATA_SOURCE class. + +<ul> +<li> +The WT_DATA_SOURCE class has three new methods: WT_DATA_SOURCE::compact, +WT_DATA_SOURCE::salvage, and WT_DATA_SOURCE::verify; applications may +require modifications to resolve compile errors. + +<li> +The \c owner argument to the WT_DATA_SOURCE::open_cursor method has been +removed; applications may require modifications to resolve compile errors. + +<li> +The \c exclusive argument to the WT_DATA_SOURCE::create method has been +removed; applications may require modifications to resolve compile errors. +</ul> +</dd> + +</dl><hr> +@section version_143 Upgrading to Version 1.4.3 +<dl> + +<dt>Statistics</dt> +<dd> +WiredTiger statistics are no longer maintained by default; to configure +statistics, use the \c statistics configuration string to the +::wiredtiger_open function. +</dd> + +</dl><hr> +@section version_139 Upgrading to Version 1.3.9 +<dl> + +<dt>Compression</dt> +<dd> +A new member, WT_COMPRESSOR::compress_raw, was added to the WT_COMPRESSOR +extension API. Applications using the WT_COMPRESSOR extension API should +add a NULL as the second field of that structure. +</dd> + +<dt>Checksums</dt> +<dd> +The WT_SESSION::create method's \c checksum configuration string has +been changed from a boolean type to a string type. Applications using +the checksum configuration string should change a value of \c true to +the string \c on, and a value of \c false to the string \c off or the +string \c uncompressed. +</dd> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.3.9 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +</dl><hr> +@section version_138 Upgrading to Version 1.3.8 +<dl> + +<dt>Statistics keys</dt> +<dd> +The @ref statistics_keys "statistics key constants" have been renamed to use +all capitals, and use consistent prefixes to distinguish between connection +statistics and statistics for data sources. +</dd> + +</dl><hr> +@section version_136 Upgrading to Version 1.3.6 +<dl> + +<dt>Installed library names</dt> +<dd> +The installed WiredTiger extension library names changed to limit +namespace pollution: + +<table> +@hrow{Library, Previous Name, New Name} +@row{Bzip2 compression, bzip2_compress.a, libwiredtiger_bzip2.a} +@row{, bzip2_compress.la, libwiredtiger_bzip2.la} +@row{, bzip2_compress.so, libwiredtiger_bzip2.so} +@row{Snappy compression, snappy_compress.a, libwiredtiger_snappy.a} +@row{, snappy_compress.la, libwiredtiger_snappy.la} +@row{, snappy_compress.so, libwiredtiger_snappy.so} +@row{No-op compression, nop_compress.a, No longer installed} +@row{, nop_compress.la, No longer installed} +@row{, nop_compress.so, No longer installed} +@row{Reverse order collator, reverse_collator.a, No longer installed} +@row{, reverse_collator.la, No longer installed} +@row{, reverse_collator.so, No longer installed} +</table> +</dd> + +<dt>Built-in compression names</dt> +<dd> +The built-in compression name arguments to the WT_SESSION:create +\c block_compressor configuration string changed for consistency: + +<table> +@hrow{Extension, Previous Name, New Name} +@row{Bzip2 compression, "bzip2_compress", "bzip2"} +@row{Snappy compression, "snappy_compress", "snappy"} +</table> +</dd> + +</dl><hr> +@section version_135 Upgrading to Version 1.3.5 +<dl> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.3.5 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +</dl><hr> +@section version_13 Upgrading to Version 1.3 +<dl> + +<dt>Checkpoint and Snapshot</dt> +<dd> +The checkpoint functionality supported by WT_SESSION::checkpoint and the +snapshot functionality supported by WT_SESSION::sync have been merged +into a single piece of functionality. + +<ul> +<li>WT_SESSION.checkpoint<br> +The WT_SESSION::checkpoint method's \c snapshot configuration string has +been renamed to \c name. The name assigned to checkpoints without a +specified \c name configuration is now \c "WiredTigerCheckpoint". + +<li>WT_SESSION.drop<br> +In releases before 1.3, the WT_SESSION::drop method was used to delete +snapshots. In 1.3, the functionality of deleting snapshots has been +moved to the WT_SESSION::checkpoint method, specifically, snapshots are +discarded using the WT_SESSION::checkpoint method's \c drop configuration +string. + +<li>WT_SESSION.sync<br> +The WT_SESSION::sync method has been removed from the 1.3 release; the +functionality of creating an object snapshot has moved to the +WT_SESSION::checkpoint method, specifically, creating a snapshot of a +one or more objects is done using the WT_SESSION::checkpoint method's +\c target configuration string. + +<li>wt drop -s<br> +The \c -s option to the \c drop command for the \c wt command line +utility has been removed, and object snapshots may no longer be removed +from the command line. + +<li>wt dump, list -s<br> +The \c -s options to the \c dump and \c list commands for the \c wt +command line utility have been renamed to be \c -c. +</ul> +</dd> + +<dt>WT_SESSION.open_cursor</dt> +<dd> +In releases before 1.3, the WT_SESSION::open_cursor method could duplicate +cursors that were not positioned in an object; in 1.3, a cursor must be +positioned in order to be duplicated. +</dd> + +<dt>Transactional cursors</dt> +<dd> +In releases before 1.3, ending a transaction by calling the +WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction methods +implicitly closed all open cursors; in 1.3, the cursors remain open, but are +reset (discarding their positions and cursor values). This means applications +must change to either close cursors explicitly, or rely on an eventual +WT_SESSION::close or WT_CONNECTION::close methods to implicitly close open +cursors. +</dd> + +<dt>Default transactional isolation level</dt> +<dd> +In releases before 1.3, the default isolation level for transaction was +\c snapshot, and the default isolation level for non-transaction operations +was \c read-uncommitted; in 1.3, the default isolation level for all +operations is \c read-committed. + +The default can be overridden for a session using the \c isolation setting +in WT_CONNECTION::open_cursor. +</dd> + +<dt>WT_SESSION.truncate</dt> +<dd> +In releases before 1.3, the WT_SESSION::truncate method required cursors used +for truncation of a cursor range to reference existing keys in the object; +in 1.3, the WT_SESSION::truncate method has been changed to allow cursors to +reference any valid key in the object's name space so applications may discard +portions of the object name space without knowing exactly what records the +object contains. +</dd> + +<dt>WT_CURSOR.equals</dt> +<dd> +In releases before 1.3, the WT_CURSOR::equals method returned zero/non-zero +to indicate cursor equality; in 1.3, the WT_CURSOR::equals method has +been replaced with WT_CURSOR::compare, which compares two cursors and +returns a cursor comparison status (less than 0, equal to 0, or greater than +0) depending on the cursors' key order. +</dd> + +<dt>File format changes</dt> +<dd> +The underlying file formats changed in the 1.3 release; tables and files +should be dumped and re-loaded into a new database. +</dd> + +</dl> +*/ |