diff options
Diffstat (limited to 'src/docs')
| -rw-r--r-- | src/docs/database-config.dox | 29 | ||||
| -rw-r--r-- | src/docs/programming.dox | 2 | ||||
| -rw-r--r-- | src/docs/upgrade.dox | 114 |
3 files changed, 101 insertions, 44 deletions
diff --git a/src/docs/database-config.dox b/src/docs/database-config.dox index b86971ca450..b8dee0be980 100644 --- a/src/docs/database-config.dox +++ b/src/docs/database-config.dox @@ -67,12 +67,27 @@ replaced with commas. @section config_base WiredTiger.basecfg file -When a WiredTiger database is created, the configuration string passed -to ::wiredtiger_open is saved to a WiredTiger home directory file named -\c WiredTiger.basecfg, and that configuration file is read whenever the -database is subsequently opened. - -Users should not edit this file, set the \c WIREDTIGER_CONFIG -environment variable or create a \c WiredTiger.config file instead. +When a WiredTiger database is created, non-default configuration +information specified to ::wiredtiger_open is saved to a WiredTiger home +directory file named \c WiredTiger.basecfg, and that configuration file +is read whenever the database is subsequently opened. + +For example, if a shared library extensions are required, those settings +will be saved to the base configuration file so it's easier to write +general-purpose applications that might not be aware of how a particular +database was created and configured. + +Users should not not edit this file, set the \c WIREDTIGER_CONFIG +environment variable or create a \c WiredTiger.config file instead, as +those settings override the settings in the base configuration file. + +This file is a potential problem for applications that want to retain +the ability to downgrade to previous releases. If a new database is +created after an upgrade, the base configuration file might have +configuration strings that would cause a previous version of the +application to fail. For this reason, applications that may want to +downgrade should configure the ::wiredtiger_open value \c config_base +to \c false so the base configuration file is not written as part of +database create. */ diff --git a/src/docs/programming.dox b/src/docs/programming.dox index 4248d9d32ed..94ba0b464c5 100644 --- a/src/docs/programming.dox +++ b/src/docs/programming.dox @@ -31,12 +31,12 @@ each of which is ordered by one or more columns. - @subpage checkpoint - @subpage durability - @subpage backup -- @subpage upgrade - @subpage async - @subpage compact - @subpage statistics - @subpage shared_cache - @subpage cursor_log +- @subpage upgrade <h2>Extending WiredTiger</h2> - @subpage extensions diff --git a/src/docs/upgrade.dox b/src/docs/upgrade.dox index b8b01dc2ec4..7952efa0343 100644 --- a/src/docs/upgrade.dox +++ b/src/docs/upgrade.dox @@ -1,41 +1,83 @@ -/*! @page upgrade Upgrading WiredTiger databases +/*! @page upgrade Upgrading and downgrading databases -There are two parts to upgrading WiredTiger installations, upgrading the -application itself and upgrading the underlying files used in the -database. +The upgrade/downgrade process is only necessary for major or minor +WiredTiger releases (releases where the major or minor version number +changed). Patch releases (where only the patch number changed), do not +contain any API or file format changes, and do not require anything +other than a link step or shared library installation for upgrading or +downgrading. However, the complete WiredTiger library must be re-built +from scratch when changing versions, as there is no guarantee modules +from one version of the library will work with modules from any other +version. + +The rest of this page discusses upgrading and downgrading WiredTiger +major and minor releases. Specifically, by upgrading, we mean migrating +an application and its databases to a newer WiredTiger release, and by +downgrading, we mean reverting to an older version. + +When upgrading or downgrading between WiredTiger releases, there are two +components to consider: the WiredTiger library API and the underlying +data files used for the database (for example, log files or B+tree +files). As part of each WiredTiger release, a new @ref upgrading documentation -section is created for the release, describing changes in the behavior -of the WiredTiger library as well as any changes to the WiredTiger API -or the format of the underlying database files that are not backward -compatible. - -Changes to the format of the underlying files are rare, changes in the -WiredTiger API and the behavior of the WiredTiger library are far more -common. - -To upgrade a WiredTiger application and database, review the information -for each release since the WiredTiger release you're currently using and -the release to which you're upgrading. You do not need to upgrade to -each new release separately, you can skip intermediate releases and -upgrade directly to the final release you plan to use. - -Changes to the WiredTiger API are usually backward compatible, that is, -you can continue to use the same configuration strings used previously -(although it will likely enhance program readability to switch to the -new version of the configuration string). - -In some cases, application APIs or logic will have to change. If at all -possible, we make such changes compile-time errors so it's not possible -to miss a required change. - -If the underlying file formats change in ways that are not backward -compatible, or if the upgrade is sufficiently complicated or lengthy -that a separate upgrade step makes the most sense, files must be -upgraded using the WT_SESSION::upgrade method. This method can be called -for any WiredTiger object. The WT_SESSION::upgrade method returns -immediately if there is no upgrade work to be done, so it can be called -whenever an object is about to be used in applications that want to -upgrade automatically. +section is created, describing changes in the WiredTiger API and in the +format of underlying files, if any. Changes to the format of the +underlying data files are extremely rare, while changes to WiredTiger +API are more common. Generally, when the WiredTiger API changes, the +changes are backward compatible and applications do not require +modifications in order to upgrade to the new release. + +Note it is not necessary to upgrade (downgrade) to intermediate +releases, you can ignore intermediate releases and upgrade (downgrade) +directly to the release you plan to use. + +To upgrade to a new release of WiredTiger: + +-# Review the information for each release after the WiredTiger release +you're currently using, up to and including the release you plan to use. +Changes to the WiredTiger API are normally backward compatible, that is, +you can continue to use the same WiredTiger configuration values used +previously. However, it will likely enhance program maintainability to +switch to newer versions of the configuration strings, as documentation +for the deprecated values will no longer be available. +<br><br> +-# Once you have reviewed the relevant release notes and modified your +application as necessary, install the new version of the application by +relinking or installing a new version of the WiredTiger shared library. +<br><br> +-# Shut down the old version of the application. +<br><br> +-# Start the new version of the application. +<br><br> +If the upgrading documentation for any release after the previous +release and up to and including the release you are using, specifies +underlying data file formats are no longer backward compatible and will +not be upgraded at run-time, a data upgrade step is required before the +data can be accessed. In this case, data files must be upgraded using +the WT_SESSION::upgrade method. + +Applications wanting the ability to downgrade to previous releases of +WiredTiger are constrained in some important ways: + +- The underlying data file formats must not have changed between the +release currently being run and the release to which you are +downgrading. In other words, data file format changes are not backward +compatible, and an upgraded data file cannot be downgraded without being +dumped and re-loaded. +<br><br> +- Applications concerned with downgrading should configure the +::wiredtiger_open \c config_base value to \c false, so WiredTiger does +not write the base configuration file file when creating databases. +Because the base configuration file is written using a current version +of the WiredTiger API, writing this file could cause applications using +previous versions of the WiredTiger API to fail. See @ref config_base +for more information. + +To downgrade to a previous release of WiredTiger: + +-# Shut down the new version of the application. +<br><br> +-# Start the old version of the application. */ |