mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
400 lines
18 KiB
HTML
400 lines
18 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Chapter 2. Upgrading from previous versions of Berkeley DB</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Upgrade Guide" />
|
||
<link rel="up" href="index.html" title="Berkeley DB Upgrade Guide" />
|
||
<link rel="prev" href="introduction.html" title="Chapter 1. Introduction" />
|
||
<link rel="next" href="upgrade_4_7_toc.html" title="Chapter 3. Upgrading Berkeley DB 4.6 applications to Berkeley DB 4.7" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Chapter 2.
|
||
Upgrading from previous versions of Berkeley DB
|
||
</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
|
||
<th width="60%" align="center"> </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="upgrade_4_7_toc.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="chapter" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title"><a id="upgrade_process"></a>Chapter 2.
|
||
Upgrading from previous versions of Berkeley DB
|
||
</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
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>
|
||
<div class="orderedlist">
|
||
<ol type="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 <span class="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>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
Shut down the old version of the application.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Remove any Berkeley DB environment using the <a href="../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
|
||
<a href="../programmer_reference/am_upgrade.html" class="olink">Database upgrade</a>
|
||
for more information.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Restart the application.
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
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>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
Shut down the old version of the application.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Run recovery on the database environment using the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method or the <a href="../api_reference/C/db_recover.html" class="olink">db_recover utility</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Remove any Berkeley DB environment using the <a href="../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>
|
||
<div class="orderedlist">
|
||
<ol type="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 <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method, or the <a href="../api_reference/C/db_recover.html" class="olink">db_recover utility</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
If you used the <a href="../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 <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method or an appropriate system utility.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Archive the database environment for catastrophic recovery using
|
||
the <code class="literal">db_archive</code> utility as described in the
|
||
<a href="../programmer_reference/transapp_archival.html" class="olink">Database and log file archival</a> section in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Recompile and install the new version of the application.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Force a checkpoint using the <a href="../api_reference/C/txncheckpoint.html" class="olink">DB_ENV->txn_checkpoint()</a> method or the <a href="../api_reference/C/db_checkpoint.html" class="olink">db_checkpoint utility</a>. If you use the
|
||
<a href="../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.
|
||
</p>
|
||
<p>
|
||
Note that forcing a checkpoint might result in warning messages
|
||
about log files that are being skipped. This is normal, and can be
|
||
safely ignored.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Remove unnecessary log files from the environment using the <code class="literal">-d</code> option on
|
||
the <a href="../api_reference/C/db_archive.html" class="olink">db_archive utility</a>, or from an application which calls the <a href="../api_reference/C/logarchive.html" class="olink">DB_ENV->log_archive()</a> method with the
|
||
<a href="../api_reference/C/logarchive.html#archive_DB_ARCH_REMOVE" class="olink">DB_ARCH_REMOVE</a> flag.
|
||
</p>
|
||
<p>
|
||
Note that removing log files in this way might result in warning messages
|
||
about log files that are being skipped. This is normal, and can be
|
||
safely ignored.
|
||
</p>
|
||
<p>
|
||
Note that if you are upgrading a replicated application, then you should
|
||
<span class="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>
|
||
<div class="orderedlist">
|
||
<ol type="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 <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method, or the <a href="../api_reference/C/db_recover.html" class="olink">db_recover utility</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
If you used the <a href="../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 <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method or an appropriate system utility.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Archive the database environment for catastrophic recovery using
|
||
the <code class="literal">db_archive</code> utility as described in the
|
||
<a href="../programmer_reference/transapp_archival.html" class="olink">Database and log file archival</a> section in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Recompile and install the new version of the application.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Upgrade the application's databases. See
|
||
<a href="../programmer_reference/am_upgrade.html" class="olink">Database upgrade</a>
|
||
for more information.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
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 <a href="../api_reference/C/txncheckpoint.html" class="olink">DB_ENV->txn_checkpoint()</a> method or the <a href="../api_reference/C/db_checkpoint.html" class="olink">db_checkpoint utility</a>. If you use the
|
||
<a href="../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.
|
||
</p>
|
||
<p>
|
||
Note that forcing a checkpoint might result in warning messages
|
||
about log files that are being skipped. This is normal, and can be
|
||
safely ignored.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Remove unnecessary log files from the environment using the <code class="literal">-d</code> option on
|
||
the <a href="../api_reference/C/db_archive.html" class="olink">db_archive utility</a>, or from an application which calls the <a href="../api_reference/C/logarchive.html" class="olink">DB_ENV->log_archive()</a> method with the
|
||
<a href="../api_reference/C/logarchive.html#archive_DB_ARCH_REMOVE" class="olink">DB_ARCH_REMOVE</a> flag.
|
||
</p>
|
||
<p>
|
||
Note that removing log files in this way might result in warning messages
|
||
about log files that are being skipped. This is normal, and can be
|
||
safely ignored.
|
||
</p>
|
||
<p>
|
||
Note that if you are upgrading a replicated application, then you should
|
||
<span class="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>
|
||
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:
|
||
</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
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)).
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Shut down the master site and upgrade that site last.
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
Also, all removal of log files must be suspended throughout this entire procedure, so that there
|
||
is no chance of a client needing internal initialization.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="upgrade_4_7_toc.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Chapter 1. Introduction </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Chapter 3. Upgrading Berkeley DB 4.6 applications to Berkeley DB 4.7</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|