WiredTiger: Upgrading WiredTiger applications

| Version 3.1.0

Fork me on GitHub Join my user group
Upgrading WiredTiger applications

# Upgrading to Version 3.1.0

WiredTiger on-disk log file format change

  The WiredTiger on-disk file format for write-ahead log files has changed as the log file version number was incremented. See WT-4029 for details.

wiredtiger_open compatibility configuration changes

  The compatibility setting now takes additional options that can define the minimum or maximum required version of existing data files. See WT-4056 and WT-4098 for details.

wiredtiger_open cache configuration changes

  The cache configuration options `eviction_checkpoint_target`, `eviction_dirty_target`, `eviction_dirty_trigger`, `eviction_target` and `eviction_trigger` have changed. The options can now take an absolute size. It would be 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. This API change is compatible with existing usage. See WT-3632 for details.

Changed transaction semantics around schema operations

  WiredTiger does not offer fully transactional create and drop operations. We have made some changes to how create and drop are implemented if done within the scope of an explicit transaction. If an application is relying on particular visibility/atomicity guarantees around table create or drop, care should be taken when upgrading. See WT-3964 for details.

On-disk format change for metadata

  There was a change to the content stored in the WiredTiger owned metadata files, which means metadata created or updated by this version of WiredTiger is not compatible with earlier versions. See WT-3905 for details.

Implement a per-session cursor cache

  WiredTiger now holds a cache of recently closed cursors in each session. This improves performance for applications that open and close cursors frequently, but increases memory overhead. The cache is enabled by default, but can be disabled. See WT-1228 for details.

# Upgrading to Version 3.0.0

WiredTiger on-disk log file format change

  The WiredTiger on-disk file format for write-ahead log files has changed to include a new internal system log record.

Addition of compatibility configuration setting

  There is now a compatibility setting that allows the user to upgrade or downgrade the log files generated so that they can be run with an older release.

Cached overflow record statistics

  The `cache_overflow_value` ("overflow values cached in memory") statistic has been removed, it no longer has any meaning.

Performance visualization tool wtstats

  The performance visualization tool `wtstats` has been removed and is no longer supported.

# Upgrading to Version 2.9.2

Logging subsystem statistics

  Two logging subsystem statistics have been removed as they were a duplicate of other statistics. The `log_slot_joins` and `log_slot_transitions` statistics are no longer present. They were duplicates of `log_writes` and `log_slot_closes` respectively. Several new logging related statistics have been added.

WiredTiger Utility now supports truncate

  The WiredTiger utility `wt` can now `truncate` objects, removing all contents from the specified object.

Handle list lock statistics

  In the 2.9.1 release we added statistics tracking handle list lock timing, we have switched that lock from a spin lock to a read-write lock, and consequently changed the statistics tracking lock related wait time.

Logging subsystem statistics

  Two logging subsystem statistics have been removed as they were a duplicate of other statistics. The `log_slot_joins` and `log_slot_transitions` statistics are no longer present. They were duplicates of `log_writes` and `log_slot_closes` respectively. Several new logging related statistics have been added.

Forced and named checkpoint error conditions changed

  There are new cases where checkpoints created with an explicit name or the "force" configuration option can return an EBUSY error. This can happen if the checkpoint overlaps with other schema operations, for example table create.

WT_CURSOR::remove may not return a positioned cursor

  The WT_CURSOR::remove method was previously documented to always return a positioned cursor on success, which is not possible when `overwrite=true` and the record does not exist.

  The documentation has been updated, and the method has been changed to never return a cursor position unless called with an existing cursor position. In other words, if the cursor is positioned and the WT_CURSOR::remove is called, the cursor will remain positioned; if the cursor is not positioned and the WT_CURSOR::remove method is called, the cursor will not be positioned on return.

# Upgrading to Version 2.9.1

Changes to hazard pointer configuration

  The `hazard_max` parameter to wiredtiger_open is now ignored. Memory is allocated for hazard pointers as required by each session.

Change to the default fadvise behavior for data files

  The old default behavior was to advise the file system that access would be random for data files, and there was no way to alter that. We no longer call advise the file system of expected access patterns by default, and have added a new `access_pattern_hint` configuration option available for WT_SESSION::create that can be used to restore the old default by setting the value to "random".

# Upgrading to Version 2.9.0

Changes to cursor behavior after WT_CURSOR::insert

  After a successful call to WT_CURSOR::insert, unless a cursor has record number keys and was configured with "append=true", the cursor's key is cleared and a subsequent call to the WT_CURSOR::get_key method will fail. In all cursors, the value is cleared and a subsequent call to WT_CURSOR::get_value will fail.

Cache management defaults

  The default values for the `eviction_dirty_target` and `eviction_dirty_trigger` settings to wiredtiger_open have changed to 5 and 20, respectively. This means that by default, WiredTiger will start writing dirty pages from cache when it becomes 5% dirty and will throttle activity to keep the volume of dirty data in cache under 20%. For write-heavy workloads, the new defaults may result in lower throughput and more threads writing to data files concurrently.

  There is also a new `eviction_checkpoint_target` setting that determines how much work is done at the beginning of a checkpoint to make the critical section of checkpoints complete more quickly.

Change to default fadvise setting for data files

  The default behavior for data files was to advise the file system to optimize for random access on POSIX and Windows platforms. The default is now to not advise about access patterns. There is a new `access_pattern_hint` configuration string available to WT_SESSION::create that can be used to configure the old default behavior.

Checkpoint server created checkpoint names

  The wiredtiger_open checkpoint configuration no longer supports the `name` configuration, and checkpoint server created checkpoints will always be named the default WiredTiger checkpoint name, "WiredTigerCheckpoint". Applications depending on the ability to set the checkpoint name for the checkpoint server will require modification.

Statistics logging path

  The wiredtiger_open statistics logging path configuration has been simplified to be only a path to a directory, and the file name component of the path may no longer be specified. Applications depending on the ability to set statistics log file names will require modification.

Removed and renamed statistics fields

  WT_STAT_JOIN_ACTUAL_COUNT is renamed to WT_STAT_JOIN_ITERATED

  WT_STAT_CONN_CACHE_BYTES_OVERFLOW removed since overflow pages are not cached

  WT_STAT_CONN_CACHE_EVICTION_SERVER_NOT_EVICTING removed since all eviction threads can now be the server

# Upgrading to Version 2.8.0

LSM metadata

  There is a change to the format of LSM metadata in this release to fix bugs in dump / load of tables of type LSM. Tables created with the old LSM metadata format will be upgraded automatically, but once updated to the new version are no longer compatible with older releases of WiredTiger.

Column-store bulk-load cursors

  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.8.0 release, column-store objects match row-store behavior and require the cursor key be set before an insert. (This 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 `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.

Change to WT_SESSION::truncate with URI

  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.

Bzip2 compression support

  Support for the bzip2 compression/decompression engine has been removed from the WiredTiger release; remaining compression engines include LZ4, snappy and zlib.

Change to named checkpoints with bulk loads

  Previous versions of WiredTiger created empty named checkpoints in files being bulk-loaded. In this release, checkpoint skips files being bulk-loaded, so they do not get named checkpoints that complete during the bulk load.

Remove WT_LSN structure from public API

  The WiredTiger public API used to define a structure that could encapsulate log sequence numbers. That structure is no longer exposed publicly.

# Upgrading to Version 2.7.0

Change to config_base=false

  If `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.

Statistic change

  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".

Change to WT_CURSOR::insert

  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.

WT_SESSION.verify

  The WT_SESSION.verify method in this release has a new configuration option, `strict`. By default, with `strict` set to `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 `strict` to `true` in order to terminate the application whenever an error is detected.

# Upgrading to Version 2.6.1

Move the per transaction sync configuration

  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.

# Upgrading to Version 2.6.0

LZ4 compression

  The LZ4 compression support has been updated in this release in non-backward compatible ways; tables and files compressed using LZ4 compression with WiredTiger 2.5.3 must be dumped then re-loaded using WiredTiger 2.6.0.

wiredtiger_open file manager configuration changes

  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.

Statistic change

  The statistic "log read operations" was removed. The function that used that statistic was never called inside WiredTiger and was also removed.

File handle closing

  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 `file_manager` configuration values to the wiredtiger_open call.

Table drop changes

  There has been a functionality change to the WT_SESSION::drop API when the `force` configuration option is included. The table is now dropped in the background and does not flush data from cache.

# Upgrading to Version 2.5.3

Configuration string case-sensitivity

  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.

Statistics cursor refresh

  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.

Buffer alignment on Linux

  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.

# Upgrading to Version 2.5.2

There are no special upgrade steps required.

# Upgrading to Version 2.5.1

Statistics cursors on data sources

  Opening a statistics cursor on a data source without a `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 `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.

# Upgrading to Version 2.5.0

WT_STAT_CONN_LOG_BYTES_USER renamed WT_STAT_CONN_LOG_BYTES_PAYLOAD

  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.

"none" configuration for collators, compressors and extractors

  Collators, compressors and extractors can now be disabled with an explicit `"none"` value as an alternative to using an empty string. Any applications using the name `"none"` for a collator, compressor or extractor will need to be updated.

maximum keys and value sizes

  The WT_SESSION::create `internal_item_max` and `leaf_item_max` configuration strings are now deprecated in favor of the `internal_key_max`, `leaf_key_max`, and `leaf_value_max` configuration strings. See Tuning page size and compression for more information.

# Upgrading to Version 2.4.1

WT_DEADLOCK renamed
  The `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.
Statistics keys changed

  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.

# Upgrading to Version 2.4.0

Default configuration file changes
  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.
Cursors no longer reset on transaction begin or commit

  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.

WT_COLLATOR interface changes
  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 `NULL`.
wiredtiger_open lsm_merge option changed
  The global lsm_merge configuration setting has been moved into the `lsm_manager` option group. To disable merges in all LSM trees pass `lsm_manger=`(merge=false) to wiredtiger_open.
Java include path search changes
  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.
Default mutex implementation changed
  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 `–with-spinlock=pthread_adaptive` at configuration time.
LSM merge threads option change

  The WT_SESSION::create `lsm=`(merge_threads) configuration option has been replaced by the W::wiredtiger_open `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.

# Upgrading to Version 2.3.1

wiredtiger_open eviction_workers configuration changed

  The `eviction_workers` configuration setting has been replaced by `eviction=`(threads_min) and `eviction=`(threads_max) settings.

  There is also a semantic change because `eviction_workers` used to configure additional threads whereas the new settings configure the total number of threads involved with eviction.

# Upgrading to Version 2.3.0

There are no special upgrade steps required.

# Upgrading to Version 2.2.1

wiredtiger_open configuration parsing order changed

  In the 2.2.1 release, the order that configuration strings are parsed and override earlier values changed. Applications using the `Wiredtiger.config` file or `WIREDTIGER_CONFIG` environment variable may need to change. The old order:

  1. default wiredtiger_open configuration
  2. base configuration file, created with the database
  3. user configuration file `Wiredtiger.config`
  4. user environment variable `WIREDTIGER_CONFIG`
  5. configuration string passed in to wiredtiger_open

  In the new order the user's configuration settings override:

  1. default wiredtiger_open configuration
  2. base configuration file, created with the database
  3. configuration string passed in to wiredtiger_open
  4. user configuration file `Wiredtiger.config`
  5. user environment variable `WIREDTIGER_CONFIG`

`os_cache_dirty_max` off for LSM

  In some earlier versions of WiredTiger, creating an LSM table automatically configured `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.

`transaction_sync` setting change

  In the 2.2.1 release of WiredTiger the wiredtiger_open `transaction_sync` configuration setting has changed from a string value to a structure with two fields: `method`, which corresponds to the previous value (`dsync`, `fsync` or `none`), and `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 `sync` setting to WT_SESSION::begin_transaction.

# Upgrading to Version 2.2.0

WT_SESSION::create prefix_compression disabled by default

  In the 2.2.0 release, prefix compression default to `false`. Applications that benefit from prefix compression will need to explicitly set `prefix_compression=true` when creating tables.

wiredtiger_open verbose message changes

  In the 2.2.0 release it is now necessary to include `–enable-verbose` in the configure command to be able to use verbose messages.

# Upgrading to Version 2.1.2

wiredtiger_open shared_cache configuration changes

  In the 2.1.2 release of WiredTiger the wiredtiger_open `shared_cache` configuration option group have changed. The option that was named `enable` is no longer available. To enable a `shared_cache` it is compulsory to name the pool being shared. We are now also enforcing that only one of `cache_size` and `shared_cache` are specified in the wiredtiger_open configuration string.

# Upgrading to Version 2.1.1

WT_EXTENSION_API::config methods

  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.

# Upgrading to Version 2.1

WT_ITEM::size type

  In the 2.1 release of WiredTiger WT_ITEM::size type has changed from `uint32_t` to `size_t`. Applications may require modifications to resolve compile-time errors.

WT_COMPRESSOR::compress_raw signature

  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 `EAGAIN`. If it returns zero and sets `result_slots` to zero, WiredTiger will assume that raw compression has failed and will fall back to calling WT_COMPRESSOR::compress.

Transaction sync default setting

  In the 2.1 release of WiredTiger the wiredtiger_open `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".

# Upgrading to Version 2.0

File format changes

  The underlying file format is unchanged in 2.0

WT_SESSION::create LSM configuration options

  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 `lsm_` now belong to the `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.

# Upgrading to Version 1.6.6

File format changes

  The underlying file formats changed in the 1.6.6 release; tables and files should be dumped and re-loaded into a new database.

WT_SESSION::compact trigger configuration

  In previous releases, the `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.

Statistics configuration

  In previous releases, the wiredtiger_open function took a `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 `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 `statistics_log` configuration which logged the performance-inexpensive database statistics to a file. In version 1.6.6, the `statistics_log` configuration logs whatever statistics are configured for the database. If the database is configured with `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 `statistics_clear` and a `statistics_fast` configurations. The `statistics_clear` configuration defaulted to false; when set to true, statistics counters were reset after they were gathered by the cursor. The `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 `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;

WT_EVENT_HANDLER interface changes

  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.

# Upgrading to Version 1.6.5

WT_CURSOR::insert behavior

  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.

WT_SESSION::open_cursor statistics_fast configuration

  In previous releases, the default `statistics_fast` configuration to the WT_SESSION::open_cursor method was `false`; in the 1.6.5 release, the default statistics_fast configuration is `true`. Applications opening statistics cursors should be reviewed to confirm they have the correct behavior.

Synchronous checkpoint configuration

  The `sync` configuration key to wiredtiger_open has been renamed `checkpoint_sync`.

# Upgrading to Version 1.6.4

File format changes

  The underlying file formats changed in the 1.6.4 release; tables and files should be dumped and re-loaded into a new database.

wt utility load command

  The default behavior of the `wt` utility's `load` command has been changed to overwrite existing data, by default, and the `-o` flag to the `load` command (overwrite existing data) has been replaced with the `-n` flag (do not overwrite existing data). Applications requiring the previous default behavior of not overwriting existing data should add the `-n` option to their command line configuration; applications previously using the `-o` option on their command line configurations should remove it.

# Upgrading to Version 1.6.3

Cursor overwrite configuration

  In previous releases, the WT_SESSION::open_cursor `overwrite` configuration string behaved inconsistently across Btree and LSM data sources. In Btree, `overwrite` was `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, `overwrite` was `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 `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, `overwrite` is `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 `overwrite` to `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.

  This is a potentially serious API change that will not be detected by compilation. Application cursors should be reviewed to confirm they are configured for the desired behavior.

wiredtiger_open no longer accepts a `transactional` configuration

  The `transactional` configuration key has been removed from wiredtiger_open. Any application setting it should simply remove it, no change in application behavior is needed.

# Upgrading to Version 1.6.2

Table of WiredTiger extension methods

  New functionality was added to the list of WiredTiger extension methods; applications using the extension methods will require recompilation.

WT_SESSION::create no longer accepts a "source" configuration

  The `"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.

Default checksum configuration

  The default file checksum configuration was changed to `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 `on`.

# Upgrading to Version 1.6.1

Default page sizes

  In the 1.6.1 release, the default for the WT_SESSION::create configuration string `allocation_size` changed from 512B to 4KB, and the default for the configuration string `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.

Shared cache configuration

  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.

WT_COMPRESSOR::compress_raw signature

  In the 1.6.1 release, the `split_pct` argument to the WT_COMPRESSOR::compress_raw function changed type from `u_int` to `int`, applications may require modification to avoid compiler warnings.

# Upgrading to Version 1.6.0

File format changes

  The underlying file formats changed in the 1.6.0 release; tables and files should be dumped and re-loaded into a new database.

# Upgrading to Version 1.5.3

Configuration strings

  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.

Loading extensions and WT_EXTENSION_API

  The following changes are only applicable to applications loading extensions and/or using the WiredTiger extension functions described in WT_EXTENSION_API.

  - The signature of wiredtiger_extension_init has changed from `(WT_SESSION *session, WT_EXTENSION_API *api)` to `(WT_CONNECTION *connection)`. 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.

  - The type of all configuration arguments to extension methods has changed from `"const char *"` to `"WT_CONFIG_ARG *"`, and the WT_EXTENSION::config method added to support configuration parsing; applications may require modifications.

  - The undocumented `wiredtiger_XXX` defines for WT_EXTENSION_API extension methods have been removed from the `wiredtiger_ext.h` include file; applications should instead use the method handles referenced by the WT_EXTENSION_API handle to call extension functions.

  - The extension API methods have all changed to require an additional parameter, the WT_EXTENSION_API method handle; applications may require modifications.

  - The WT_SESSION::msg_printf method was replaced by WT_EXTENSION_API::msg_printf; applications may require modifications.

WT_DATA_SOURCE

  The following changes are only applicable to applications providing new implementations of the WiredTiger WT_DATA_SOURCE class.

  - 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.

  - The `owner` argument to the WT_DATA_SOURCE::open_cursor method has been removed; applications may require modifications to resolve compile errors.

  - The `exclusive` argument to the WT_DATA_SOURCE::create method has been removed; applications may require modifications to resolve compile errors.

# Upgrading to Version 1.4.3

Statistics

  WiredTiger statistics are no longer maintained by default; to configure statistics, use the `statistics` configuration string to the wiredtiger_open function.

# Upgrading to Version 1.3.9

Compression

  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.

Checksums

  The WT_SESSION::create method's `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 `true` to the string `on`, and a value of `false` to the string `off` or the string `uncompressed`.

File format changes

  The underlying file formats changed in the 1.3.9 release; tables and files should be dumped and re-loaded into a new database.

# Upgrading to Version 1.3.8

Statistics keys

  The statistics key constants have been renamed to use all capitals, and use consistent prefixes to distinguish between connection statistics and statistics for data sources.

# Upgrading to Version 1.3.6

Installed library names

  The installed WiredTiger extension library names changed to limit namespace pollution:

  Library | Previous Name | New Name
  --- | --- | ---
  Bzip2 compression | bzip2_compress.a | libwiredtiger_bzip2.a
  | bzip2_compress.la | libwiredtiger_bzip2.la
  | bzip2_compress.so | libwiredtiger_bzip2.so
  Snappy compression | snappy_compress.a | libwiredtiger_snappy.a
  | snappy_compress.la | libwiredtiger_snappy.la
  | snappy_compress.so | libwiredtiger_snappy.so
  No-op compression | nop_compress.a | No longer installed
  | nop_compress.la | No longer installed
  | nop_compress.so | No longer installed
  Reverse order collator | reverse_collator.a | No longer installed
  | reverse_collator.la | No longer installed
  | reverse_collator.so | No longer installed

Built-in compression names

  The built-in compression name arguments to the WT_SESSION:create `block_compressor` configuration string changed for consistency:

  Extension | Previous Name | New Name
  --- | --- | ---
  Bzip2 compression | "bzip2_compress" | "bzip2"
  Snappy compression | "snappy_compress" | "snappy"

# Upgrading to Version 1.3.5

File format changes

  The underlying file formats changed in the 1.3.5 release; tables and files should be dumped and re-loaded into a new database.

# Upgrading to Version 1.3

Checkpoint and Snapshot

  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.

  - WT_SESSION.checkpoint
    The WT_SESSION::checkpoint method's `snapshot` configuration string has been renamed to `name`. The name assigned to checkpoints without a specified `name` configuration is now `"WiredTigerCheckpoint"`.

  - WT_SESSION.drop
    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 `drop` configuration string.

  - WT_SESSION.sync
    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 `target` configuration string.

  - wt drop -s
    The `-s` option to the `drop` command for the `wt` command line utility has been removed, and object snapshots may no longer be removed from the command line.

  - wt dump, list -s
    The `-s` options to the `dump` and `list` commands for the `wt` command line utility have been renamed to be `-c`.

WT_SESSION.open_cursor

  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.

Transactional cursors

  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.

Default transactional isolation level

  In releases before 1.3, the default isolation level for transaction was `snapshot`, and the default isolation level for non-transaction operations was `read-uncommitted`; in 1.3, the default isolation level for all operations is `read-committed`.

  The default can be overridden for a session using the `isolation` setting in WT_CONNECTION::open_cursor.

WT_SESSION.truncate

  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.

WT_CURSOR.equals

  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.

File format changes

  The underlying file formats changed in the 1.3 release; tables and files should be dumped and re-loaded into a new database.