Edit File - File Manager

Edit File: process.html

<html>
<head>
<title>Berkeley DB Reference Guide: Upgrading Berkeley DB installations</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></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>
</td></tr></table>
Upgrading Berkeley DB installations
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.
Each Berkeley DB major or minor release has information in this chapter of
the Reference Guide, describing how to upgrade to the new release. The
section 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
section includes a page 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.
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.
If the release is a patch release, do the following:
<ol>
<li>Shut down the old version of the application.
<li>Install the new version of the application by relinking or installing
a new version of the Berkeley DB shared library.
<li>Restart the application.
</ol>
Otherwise, if the application does not have a Berkeley DB
transactional environment, the application may be installed in the field
using the following steps:
<ol>
<li>Shut down the old version of the application.
<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV-&gt;remove</a> method or an
appropriate system utility.
<li>Recompile and install the new version of the application.
<li>If necessary, upgrade the application's databases. See
<a href="../../ref/am/upgrade.html">Upgrading databases</a> for more
information.
<li>Restart the application.
</ol>
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:
<ol>
<li>Shut down the old version of the application.
<li>Run recovery on the database environment using the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method
or the <a href="../../utility/db_recover.html">db_recover</a> utility.
<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV-&gt;remove</a> method or an
appropriate system utility.
<li>Recompile and install the new version of the application.
<li>Restart the application.
</ol>
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:
<ol>
<li>Shut down the old version of the application.
<li>Still using the old version of Berkeley DB, run recovery on the database
environment using the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method or the <a href="../../utility/db_recover.html">db_recover</a>
utility.
<li>If you used the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method to run recovery, make sure that the
Berkeley DB environment is removed using the <a href="../../api_c/env_remove.html">DB_ENV-&gt;remove</a> method or an
appropriate system utility. 
<li>Archive the database environment for catastrophic recovery. See
<a href="../../ref/transapp/archival.html">Archival procedures</a> for more
information.
<li>Recompile and install the new version of the application.
<li>Force a checkpoint using the <a href="../../api_c/txn_checkpoint.html">DB_ENV-&gt;txn_checkpoint</a> method or the
<a href="../../utility/db_checkpoint.html">db_checkpoint</a> utility. If you use the <a href="../../utility/db_checkpoint.html">db_checkpoint</a>
utility, 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.
<li>Restart the application.
</ol>
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:
<ol>
<li>Shut down the old version of the application.
<li>Still using the old version of Berkeley DB, run recovery on the database
environment using the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method or the <a href="../../utility/db_recover.html">db_recover</a>
utility.
<li>If you used the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method to run recovery, make sure that the
Berkeley DB environment is removed using the <a href="../../api_c/env_remove.html">DB_ENV-&gt;remove</a> method or an
appropriate system utility. 
<li>Archive the database environment for catastrophic recovery. See
<a href="../../ref/transapp/archival.html">Archival procedures</a> for more
information.
<li>Recompile and install the new version of the application.
<li>Upgrade the application's databases. See
<a href="../../ref/am/upgrade.html">Upgrading databases</a> for more
information.
<li>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.
<li>Force a checkpoint using the <a href="../../api_c/txn_checkpoint.html">DB_ENV-&gt;txn_checkpoint</a> method or the
<a href="../../utility/db_checkpoint.html">db_checkpoint</a> utility. If you use the <a href="../../utility/db_checkpoint.html">db_checkpoint</a>
utility, 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.
<li>Restart the application.
</ol>
Finally, Berkeley DB supports the live upgrade of a replication
group, by allowing mixed version operation (replication sites
running at the newer software version can inter-operate with older
version sites). All client sites must be upgraded first; the
master site must be upgraded last. In other words, at all times
the master must be running the lowest version of Berkeley DB.
To upgrade a replication group, you must:
<ol>
<li>Bring all clients up to date with the master (that is, all
clients must be brought up to the most current log record as measured
by the master's log sequence number (LSN)).
<li>Perform the upgrade procedures described previously on each
of the individual database environments that are part of the replication
group. Each individual client may be upgraded and restarted to join
the replication group.
<li>Shut down the master site and upgrade that site last.
</ol>
During live replication upgrade, while sites are running at different
versions, adding new (empty) clients to the replication group is not
allowed. Those empty client environments must be added after the
entire group is upgraded.
Alternatively, it may be simpler to discard the contents of all of the
client database environments, upgrade the master database environment,
and then re-add all of the clients to the replication group using the
standard replication procedures for new sites.
<table width="100%"><tr><td> </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>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>

Back to File Manager