1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
|
<?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>Upgrading Berkeley DB installations</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 Programmer's Reference Guide" />
<link rel="up" href="upgrade.html" title="Chapter 31. Upgrading from previous versions of Berkeley DB" />
<link rel="prev" href="upgrade.html" title="Chapter 31. Upgrading from previous versions of Berkeley DB" />
<link rel="next" href="upgrade_2_0_toc.html" title="Chapter 32. Upgrading Berkeley DB 1.85 or 1.86 applications to Berkeley DB 2.0" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Upgrading Berkeley DB installations</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td>
<th width="60%" align="center">Chapter 31.
Upgrading from previous versions of Berkeley DB
</th>
<td width="20%" align="right"> <a accesskey="n" href="upgrade_2_0_toc.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="upgrade_process"></a>Upgrading Berkeley DB installations</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 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.
</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 class="xref" href="am_upgrade.html" title="Database upgrade">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> utility.
</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. See
<a class="xref" href="transapp_archival.html" title="Database and log file archival">Database and log file archival</a>
for more information.
</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>
</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 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> utility.
</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. See
<a class="xref" href="transapp_archival.html" title="Database and log file archival">Database and log file archival</a>
for more information.
</p>
</li>
<li>
<p>
Recompile and install the new version of the application.
</p>
</li>
<li>
<p>
Upgrade the application's databases. See
<a class="xref" href="am_upgrade.html" title="Database upgrade">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>
</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 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="upgrade.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="upgrade.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="upgrade_2_0_toc.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 31.
Upgrading from previous versions of Berkeley DB
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 32. Upgrading Berkeley DB 1.85 or 1.86 applications to Berkeley DB 2.0</td>
</tr>
</table>
</div>
</body>
</html>
|
