1<!--$Id: process.so,v 1.16 2008/03/17 16:10:24 sue Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Upgrading Berkeley DB installations</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></b></td> 13<td align=right><a href="/upgrade/version.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/changelog/toc.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Upgrading Berkeley DB installations</b></p> 16<p>The following information describes the general process of upgrading 17Berkeley DB installations. There are four areas to be considered when 18upgrading Berkeley DB applications and database environments: the application 19API, the database environment's region files, the underlying database 20formats, and, in the case of transactional database environments, the 21log files. The upgrade procedures required depend on whether or not 22the release is a major or minor release (in which either the major or 23minor number of the version changed), or a patch release (in which only 24the patch number in the version changed). Berkeley DB major and minor 25releases may optionally include changes in all four areas, that is, the 26application API, region files, database formats, and log files may not 27be backward-compatible with previous releases.</p> 28<p>Each Berkeley DB major or minor release has information in this chapter of 29the Reference Guide, describing how to upgrade to the new release. The 30section describes any API changes made in the release. Application 31maintainers should review the API changes and update their applications 32as necessary before recompiling with the new release. In addition, each 33section includes a page specifying whether the log file format or 34database formats changed in non-backward-compatible ways as part of the 35release. Because there are several underlying Berkeley DB database formats, 36and they do not all necessarily change in the same release, changes to 37a database format in a release may not affect any particular 38application. Further, database and log file formats may have changed 39but be entirely backward-compatible, in which case no upgrade will be 40necessary.</p> 41<p>A Berkeley DB patch release will never modify the API, regions, log files, or 42database formats in incompatible ways, and so applications need only be 43relinked (or, in the case of a shared library, pointed at the new 44version of the shared library) to upgrade to a new release. Note that 45internal Berkeley DB interfaces may change at any time and in any release 46(including patch releases) without warning. This means the library must 47be entirely recompiled and reinstalled when upgrading to new releases 48of the library because there is no guarantee that modules from one 49version of the library will interact correctly with modules from another 50release. We recommend using the same compiler release when building 51patch releases as was used to build the original release; in the default 52configuration, the Berkeley DB library shares data structures from underlying 53shared memory between threads of control, and should the compiler 54re-order fields or otherwise change those data structures between the 55two builds, errors may result.</p> 56<p>If the release is a patch release, do the following:</p> 57<ol> 58<p><li>Shut down the old version of the application. 59<li>Install the new version of the application by relinking or installing 60a new version of the Berkeley DB shared library. 61<li>Restart the application. 62</ol> 63<p>Otherwise, if the application <b>does not</b> have a Berkeley DB 64transactional environment, the application may be installed in the field 65using the following steps:</p> 66<ol> 67<p><li>Shut down the old version of the application. 68<li>Remove any Berkeley DB environment using the <a href="/api_c/env_remove.html">DB_ENV->remove</a> method or an 69appropriate system utility. 70<li>Recompile and install the new version of the application. 71<li>If necessary, upgrade the application's databases. See 72<a href="/ref/am/upgrade.html">Upgrading databases</a> for more 73information. 74<li>Restart the application. 75</ol> 76<p>Otherwise, if the application has a Berkeley DB transactional environment, 77but neither the log file nor database formats need upgrading, the 78application may be installed in the field using the following steps:</p> 79<ol> 80<p><li>Shut down the old version of the application. 81<li>Run recovery on the database environment using the <a href="/api_c/env_open.html">DB_ENV->open</a> method 82or the <a href="/utility/db_recover.html">db_recover</a> utility. 83<li>Remove any Berkeley DB environment using the <a href="/api_c/env_remove.html">DB_ENV->remove</a> method or an 84appropriate system utility. 85<li>Recompile and install the new version of the application. 86<li>Restart the application. 87</ol> 88<p>If the application has a Berkeley DB transactional environment, and the log 89files need upgrading but the databases do not, the application may be 90installed in the field using the following steps:</p> 91<ol> 92<p><li>Shut down the old version of the application. 93<li>Still using the old version of Berkeley DB, run recovery on the database 94environment using the <a href="/api_c/env_open.html">DB_ENV->open</a> method or the <a href="/utility/db_recover.html">db_recover</a> 95utility. 96<li>If you used the <a href="/api_c/env_open.html">DB_ENV->open</a> method to run recovery, make sure that the 97Berkeley DB environment is removed using the <a href="/api_c/env_remove.html">DB_ENV->remove</a> method or an 98appropriate system utility. 99<li>Archive the database environment for catastrophic recovery. See 100<a href="/ref/transapp/archival.html">Archival procedures</a> for more 101information. 102<li>Recompile and install the new version of the application. 103<li>Force a checkpoint using the <a href="/api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> method or the 104<a href="/utility/db_checkpoint.html">db_checkpoint</a> utility. If you use the <a href="/utility/db_checkpoint.html">db_checkpoint</a> 105utility, make sure to use the new version of the utility; that is, the 106version that came with the release of Berkeley DB to which you are upgrading. 107<li>Restart the application. 108</ol> 109<p>Otherwise, if the application has a Berkeley DB transactional environment and 110the databases need upgrading, the application may be installed in the 111field using the following steps:</p> 112<ol> 113<p><li>Shut down the old version of the application. 114<li>Still using the old version of Berkeley DB, run recovery on the database 115environment using the <a href="/api_c/env_open.html">DB_ENV->open</a> method or the <a href="/utility/db_recover.html">db_recover</a> 116utility. 117<li>If you used the <a href="/api_c/env_open.html">DB_ENV->open</a> method to run recovery, make sure that the 118Berkeley DB environment is removed using the <a href="/api_c/env_remove.html">DB_ENV->remove</a> method or an 119appropriate system utility. 120<li>Archive the database environment for catastrophic recovery. See 121<a href="/ref/transapp/archival.html">Archival procedures</a> for more 122information. 123<li>Recompile and install the new version of the application. 124<li>Upgrade the application's databases. See 125<a href="/ref/am/upgrade.html">Upgrading databases</a> for more 126information. 127<li>Archive the database for catastrophic recovery again (using different 128media than before, of course). Note: This archival is not strictly 129necessary. However, if you have to perform catastrophic recovery after 130restarting the application, that recovery must be done based on the 131last archive you have made. If you make this second archive, you can 132use it as the basis of that catastrophic recovery. If you do not make 133this second archive, you have to use the archive you made in step 4 as 134the basis of your recovery, and you have to do a full upgrade on it 135before you can apply log files created after the upgrade to it. 136<li>Force a checkpoint using the <a href="/api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> method or the 137<a href="/utility/db_checkpoint.html">db_checkpoint</a> utility. If you use the <a href="/utility/db_checkpoint.html">db_checkpoint</a> 138utility, make sure to use the new version of the utility; that is, the 139version that came with the release of Berkeley DB to which you are upgrading. 140<li>Restart the application. 141</ol> 142<p>Finally, Berkeley DB supports the live upgrade of a replication 143group, by allowing mixed version operation (replication sites 144running at the newer software version can inter-operate with older 145version sites). All client sites must be upgraded first; the 146master site must be upgraded last. In other words, at all times 147the master must be running the lowest version of Berkeley DB. 148To upgrade a replication group, you must:</p> 149<ol> 150<p><li>Bring all clients up to date with the master (that is, all 151clients must be brought up to the most current log record as measured 152by the master's log sequence number (LSN)). 153<li>Perform the upgrade procedures described previously on each 154of the individual database environments that are part of the replication 155group. Each individual client may be upgraded and restarted to join 156the replication group. 157<li>Shut down the master site and upgrade that site last. 158</ol> 159<p>During live replication upgrade, while sites are running at different 160versions, adding new (empty) clients to the replication group is not 161allowed. Those empty client environments must be added after the 162entire group is upgraded.</p> 163<p>Alternatively, it may be simpler to discard the contents of all of the 164client database environments, upgrade the master database environment, 165and then re-add all of the clients to the replication group using the 166standard replication procedures for new sites.</p> 167<table width="100%"><tr><td><br></td><td align=right><a href="/upgrade/version.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/changelog/toc.html"><img src="/images/next.gif" alt="Next"></a> 168</td></tr></table> 169<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 170</body> 171</html> 172
