The following information describes the general process of upgrading Berkeley DB installations.
There are four areas to be considered when upgrading Berkeley DB applications and database
environments: the application API, the database environment's region files, the underlying
database formats, and, in the case of transactional database environments, the log files. The
upgrade procedures required depend on whether or not the release is a major or minor release (in
which either the major or minor number of the version changed), or a patch release (in which
only the patch number in the version changed). Berkeley DB major and minor releases may
optionally include changes in all four areas, that is, the application API, region files,
database formats, and log files may not be backward-compatible with previous releases.
</p>
<p>
Each Berkeley DB major or minor release described in this book has a chapter indicating how to
upgrade to the new release. The chapter describes any API changes made in the release.
Application maintainers should review the API changes and update their applications as necessary
before recompiling with the new release. In addition, each chapter includes a section specifying
whether the log file format or database formats changed in non-backward-compatible ways as part
of the release. Because there are several underlying Berkeley DB database formats, and they do
not all necessarily change in the same release, changes to a database format in a release may
not affect any particular application. Further, database and log file formats may have changed
but be entirely backward-compatible, in which case no upgrade will be necessary.
</p>
<p>
A Berkeley DB patch release will never modify the API, regions, log files, or database formats
in incompatible ways, and so applications need only be relinked (or, in the case of a shared
library, pointed at the new version of the shared library) to upgrade to a new release. Note
that internal Berkeley DB interfaces may change at any time and in any release (including patch
releases) without warning. This means the library must be entirely recompiled and reinstalled
when upgrading to new releases of the library because there is no guarantee that modules from
one version of the library will interact correctly with modules from another release. We
recommend using the same compiler release when building patch releases as was used to build the
original release; in the default configuration, the Berkeley DB library shares data structures
from underlying shared memory between threads of control, and should the compiler re-order
fields or otherwise change those data structures between the two builds, errors may result.
</p>
<p>
If the release is a patch release, do the following:
</p>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
Shut down the old version of the application.
</p>
</li>
<li>
<p>
Install the new version of the application by relinking or installing a new version of the
Berkeley DB shared library.
</p>
</li>
<li>
<p>
Restart the application.
</p>
</li>
</ol>
</div>
<p>
Otherwise, if the application <spanclass="bold"><strong>does not</strong></span> have a Berkeley DB
transactional environment, the application may be installed in the field using the following
steps:
</p>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
Shut down the old version of the application.
</p>
</li>
<li>
<p>
Remove any Berkeley DB environment using the <ahref="../api_reference/C/envremove.html"class="olink">DB_ENV->remove()</a> method or an appropriate system
utility.
</p>
</li>
<li>
<p>
Recompile and install the new version of the application.
</p>
</li>
<li>
<p>
If necessary, upgrade the application's databases. See
Otherwise, if the application has a Berkeley DB transactional environment, but neither the log
file nor database formats need upgrading, the application may be installed in the field using
the following steps:
</p>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
Shut down the old version of the application.
</p>
</li>
<li>
<p>
Run recovery on the database environment using the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method or the <ahref="../api_reference/C/db_recover.html"class="olink">db_recover utility</a>.
</p>
</li>
<li>
<p>
Remove any Berkeley DB environment using the <ahref="../api_reference/C/envremove.html"class="olink">DB_ENV->remove()</a> method or an appropriate system
utility.
</p>
</li>
<li>
<p>
Recompile and install the new version of the application.
</p>
</li>
<li>
<p>
Restart the application.
</p>
</li>
</ol>
</div>
<p>
If the application has a Berkeley DB transactional environment, and the log files need upgrading
but the databases do not, the application may be installed in the field using the following
steps:
</p>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
Shut down the old version of the application.
</p>
</li>
<li>
<p>
Still using the old version of Berkeley DB, run recovery on the database environment using
the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method, or the <ahref="../api_reference/C/db_recover.html"class="olink">db_recover utility</a>.
</p>
</li>
<li>
<p>
If you used the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method to run recovery, make sure that the Berkeley DB environment
is removed using the <ahref="../api_reference/C/envremove.html"class="olink">DB_ENV->remove()</a> method or an appropriate system utility.
Archive the database environment for catastrophic recovery using
the <codeclass="literal">db_archive</code> utility as described in the
<ahref="../programmer_reference/transapp_archival.html"class="olink">Database and log file archival</a> section in the <emclass="citetitle">Berkeley DB Programmer's Reference Guide</em>.
Recompile and install the new version of the application.
</p>
</li>
<li>
<p>
Force a checkpoint using the <ahref="../api_reference/C/txncheckpoint.html"class="olink">DB_ENV->txn_checkpoint()</a> method or the <ahref="../api_reference/C/db_checkpoint.html"class="olink">db_checkpoint utility</a>. If you use the
<ahref="../api_reference/C/db_checkpoint.html"class="olink">db_checkpoint utility</a>, make sure to use the new version of the utility; that is, the version that
came with the release of Berkeley DB to which you are upgrading.
Remove unnecessary log files from the environment using the <codeclass="literal">-d</code> option on
the <ahref="../api_reference/C/db_archive.html"class="olink">db_archive utility</a>, or from an application which calls the <ahref="../api_reference/C/logarchive.html"class="olink">DB_ENV->log_archive()</a> method with the
Note that if you are upgrading a replicated application, then you should
<spanclass="emphasis"><em>not</em></span> perform this step until all of the replication sites have been
upgraded to the current release level. If you run this site before all your sites are
upgraded, then errors can occur in your replication activities because important version
information might be lost.
</p>
</li>
<li>
<p>
Restart the application.
</p>
</li>
</ol>
</div>
<p>
Otherwise, if the application has a Berkeley DB transactional environment and the databases need
upgrading, the application may be installed in the field using the following steps:
</p>
<divclass="orderedlist">
<oltype="1">
<li>
<p>
Shut down the old version of the application.
</p>
</li>
<li>
<p>
Still using the old version of Berkeley DB, run recovery on the database environment using
the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method, or the <ahref="../api_reference/C/db_recover.html"class="olink">db_recover utility</a>.
</p>
</li>
<li>
<p>
If you used the <ahref="../api_reference/C/envopen.html"class="olink">DB_ENV->open()</a> method to run recovery, make sure that the Berkeley DB environment
is removed using the <ahref="../api_reference/C/envremove.html"class="olink">DB_ENV->remove()</a> method or an appropriate system utility.
Archive the database environment for catastrophic recovery using
the <codeclass="literal">db_archive</code> utility as described in the
<ahref="../programmer_reference/transapp_archival.html"class="olink">Database and log file archival</a> section in the <emclass="citetitle">Berkeley DB Programmer's Reference Guide</em>.
Archive the database for catastrophic recovery again (using different media than before, of
course). Note: This archival is not strictly necessary. However, if you have to perform
catastrophic recovery after restarting the application, that recovery must be done based on
the last archive you have made. If you make this second archive, you can use it as the
basis of that catastrophic recovery. If you do not make this second archive, you have to
use the archive you made in step 4 as the basis of your recovery, and you have to do a full
upgrade on it before you can apply log files created after the upgrade to it.
</p>
</li>
<li>
<p>
Force a checkpoint using the <ahref="../api_reference/C/txncheckpoint.html"class="olink">DB_ENV->txn_checkpoint()</a> method or the <ahref="../api_reference/C/db_checkpoint.html"class="olink">db_checkpoint utility</a>. If you use the
<ahref="../api_reference/C/db_checkpoint.html"class="olink">db_checkpoint utility</a>, make sure to use the new version of the utility; that is, the version that
came with the release of Berkeley DB to which you are upgrading.
Remove unnecessary log files from the environment using the <codeclass="literal">-d</code> option on
the <ahref="../api_reference/C/db_archive.html"class="olink">db_archive utility</a>, or from an application which calls the <ahref="../api_reference/C/logarchive.html"class="olink">DB_ENV->log_archive()</a> method with the
