path: root/src/third_party/wiredtiger/src/docs/upgrading.dox

/*! @page upgrading Upgrading WiredTiger applications

@section version_281 Upgrading to Version 2.8.1
<dl>
<dt>Cache management defaults</dt>
<dd>
The default values for the \c eviction_dirty_target and \c
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 \c 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.
</dd>

<dt>Checkpoint server created checkpoint names</dt>
<dd>
The ::wiredtiger_open checkpoint configuration no longer supports the
\c 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.
</dd>

<dt>Statistics logging path</dt>
<dd>
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.
</dd>

<dt>Deprecated statistics field</dt>
<dd>
The connection statistic \c WT_STAT_CONN_CACHE_BYTES_OVERFLOW has been
removed.  Overflow information is now available in the
\c WT_STAT_CONN_CACHE_BYTES_OVERFLOW and \c WT_STAT_CONN_CACHE_OVERFLOW_VALUE.
Applications specifically looking for that statistic will require
modification.
</dd>

</dl><hr>
@section version_280 Upgrading to Version 2.8.0
<dl>
<dt>LSM metadata</dt>
<dd>
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
<b>are no longer compatible with older releases of WiredTiger</b>.
</dd>

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

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

<dt>Change to named checkpoints with bulk loads</dt>
<dd>
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.
</dd>

<dt>Remove WT_LSN structure from public API</dt>
<dd>
The WiredTiger public API used to define a structure that could encapsulate
log sequence numbers. That structure is no longer exposed publicly.
</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>
*/