1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Upgrading Berkeley DB installations</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="upgrade.html" title="Chapter��31.�� Upgrading from previous versions of Berkeley DB" /> 11 <link rel="prev" href="upgrade.html" title="Chapter��31.�� Upgrading from previous versions of Berkeley DB" /> 12 <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" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Upgrading Berkeley DB installations</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��31.�� 23 Upgrading from previous versions of Berkeley DB 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="upgrade_2_0_toc.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="upgrade_process"></a>Upgrading Berkeley DB installations</h2> 35 </div> 36 </div> 37 </div> 38 <p> 39 The following information describes the general process of upgrading Berkeley DB installations. 40 There are four areas to be considered when upgrading Berkeley DB applications and database 41 environments: the application API, the database environment's region files, the underlying 42 database formats, and, in the case of transactional database environments, the log files. The 43 upgrade procedures required depend on whether or not the release is a major or minor release (in 44 which either the major or minor number of the version changed), or a patch release (in which 45 only the patch number in the version changed). Berkeley DB major and minor releases may 46 optionally include changes in all four areas, that is, the application API, region files, 47 database formats, and log files may not be backward-compatible with previous releases. 48</p> 49 <p> 50 Each Berkeley DB major or minor release has information in this chapter of the Reference Guide, 51 describing how to upgrade to the new release. The section describes any API changes made in the 52 release. Application maintainers should review the API changes and update their applications as 53 necessary before recompiling with the new release. In addition, each section includes a page 54 specifying whether the log file format or database formats changed in non-backward-compatible 55 ways as part of the release. Because there are several underlying Berkeley DB database formats, 56 and they do not all necessarily change in the same release, changes to a database format in a 57 release may not affect any particular application. Further, database and log file formats may 58 have changed but be entirely backward-compatible, in which case no upgrade will be necessary. 59</p> 60 <p> 61 A Berkeley DB patch release will never modify the API, regions, log files, or database formats 62 in incompatible ways, and so applications need only be relinked (or, in the case of a shared 63 library, pointed at the new version of the shared library) to upgrade to a new release. Note 64 that internal Berkeley DB interfaces may change at any time and in any release (including patch 65 releases) without warning. This means the library must be entirely recompiled and reinstalled 66 when upgrading to new releases of the library because there is no guarantee that modules from 67 one version of the library will interact correctly with modules from another release. We 68 recommend using the same compiler release when building patch releases as was used to build the 69 original release; in the default configuration, the Berkeley DB library shares data structures 70 from underlying shared memory between threads of control, and should the compiler re-order 71 fields or otherwise change those data structures between the two builds, errors may result. 72</p> 73 <p> 74 If the release is a patch release, do the following: 75</p> 76 <div class="orderedlist"> 77 <ol type="1"> 78 <li> 79 <p> 80 Shut down the old version of the application. 81 </p> 82 </li> 83 <li> 84 <p> 85 Install the new version of the application by relinking or installing a new version of the 86 Berkeley DB shared library. 87 </p> 88 </li> 89 <li> 90 <p> 91 Restart the application. 92 </p> 93 </li> 94 </ol> 95 </div> 96 <p> 97 Otherwise, if the application <span class="bold"><strong>does not</strong></span> have a Berkeley DB 98 transactional environment, the application may be installed in the field using the following 99 steps: 100</p> 101 <div class="orderedlist"> 102 <ol type="1"> 103 <li> 104 <p> 105 Shut down the old version of the application. 106 </p> 107 </li> 108 <li> 109 <p> 110 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 111 utility. 112 </p> 113 </li> 114 <li> 115 <p> 116 Recompile and install the new version of the application. 117 </p> 118 </li> 119 <li> 120 <p> 121 If necessary, upgrade the application's databases. See 122 <a class="xref" href="am_upgrade.html" title="Database upgrade">Database upgrade</a> 123 for more information. 124 </p> 125 </li> 126 <li> 127 <p> 128 Restart the application. 129 </p> 130 </li> 131 </ol> 132 </div> 133 <p> 134 Otherwise, if the application has a Berkeley DB transactional environment, but neither the log 135 file nor database formats need upgrading, the application may be installed in the field using 136 the following steps: 137</p> 138 <div class="orderedlist"> 139 <ol type="1"> 140 <li> 141 <p> 142 Shut down the old version of the application. 143 </p> 144 </li> 145 <li> 146 <p> 147 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>. 148 </p> 149 </li> 150 <li> 151 <p> 152 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 153 utility. 154 </p> 155 </li> 156 <li> 157 <p> 158 Recompile and install the new version of the application. 159 </p> 160 </li> 161 <li> 162 <p> 163 Restart the application. 164 </p> 165 </li> 166 </ol> 167 </div> 168 <p> 169 If the application has a Berkeley DB transactional environment, and the log files need upgrading 170 but the databases do not, the application may be installed in the field using the following 171 steps: 172</p> 173 <div class="orderedlist"> 174 <ol type="1"> 175 <li> 176 <p> 177 Shut down the old version of the application. 178 </p> 179 </li> 180 <li> 181 <p> 182 Still using the old version of Berkeley DB, run recovery on the database environment using 183 the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> utility. 184 </p> 185 </li> 186 <li> 187 <p> 188 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 189 is removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method or an appropriate system utility. 190 </p> 191 </li> 192 <li> 193 <p> 194 Archive the database environment for catastrophic recovery. See 195 <a class="xref" href="transapp_archival.html" title="Database and log file archival">Database and log file archival</a> 196 for more information. 197 </p> 198 </li> 199 <li> 200 <p> 201 Recompile and install the new version of the application. 202 </p> 203 </li> 204 <li> 205 <p> 206 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 207 <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 208 came with the release of Berkeley DB to which you are upgrading. 209 </p> 210 </li> 211 <li> 212 <p> 213 Remove unnecessary log files from the environment using the <code class="literal">-d</code> option on 214 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 215 <a href="../api_reference/C/logarchive.html#archive_DB_ARCH_REMOVE" class="olink">DB_ARCH_REMOVE</a> flag. 216 </p> 217 <p> 218 Note that if you are upgrading a replicated application, then you should 219 <span class="emphasis"><em>not</em></span> perform this step until all of the replication sites have been 220 upgraded to the current release level. If you run this site before all your sites are 221 upgraded, then errors can occur in your replication activities because important version 222 information might be lost. 223 </p> 224 </li> 225 <li> 226 <p> 227 Restart the application. 228 </p> 229 </li> 230 </ol> 231 </div> 232 <p> 233 Otherwise, if the application has a Berkeley DB transactional environment and the databases need 234 upgrading, the application may be installed in the field using the following steps: 235</p> 236 <div class="orderedlist"> 237 <ol type="1"> 238 <li> 239 <p> 240 Shut down the old version of the application. 241 </p> 242 </li> 243 <li> 244 <p> 245 Still using the old version of Berkeley DB, run recovery on the database environment using 246 the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> utility. 247 </p> 248 </li> 249 <li> 250 <p> 251 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 252 is removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method or an appropriate system utility. 253 </p> 254 </li> 255 <li> 256 <p> 257 Archive the database environment for catastrophic recovery. See 258 <a class="xref" href="transapp_archival.html" title="Database and log file archival">Database and log file archival</a> 259 for more information. 260 </p> 261 </li> 262 <li> 263 <p> 264 Recompile and install the new version of the application. 265 </p> 266 </li> 267 <li> 268 <p> 269 Upgrade the application's databases. See 270 <a class="xref" href="am_upgrade.html" title="Database upgrade">Database upgrade</a> 271 for more information. 272 </p> 273 </li> 274 <li> 275 <p> 276 Archive the database for catastrophic recovery again (using different media than before, of 277 course). Note: This archival is not strictly necessary. However, if you have to perform 278 catastrophic recovery after restarting the application, that recovery must be done based on 279 the last archive you have made. If you make this second archive, you can use it as the 280 basis of that catastrophic recovery. If you do not make this second archive, you have to 281 use the archive you made in step 4 as the basis of your recovery, and you have to do a full 282 upgrade on it before you can apply log files created after the upgrade to it. 283 </p> 284 </li> 285 <li> 286 <p> 287 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 288 <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 289 came with the release of Berkeley DB to which you are upgrading. 290 </p> 291 </li> 292 <li> 293 <p> 294 Remove unnecessary log files from the environment using the <code class="literal">-d</code> option on 295 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 296 <a href="../api_reference/C/logarchive.html#archive_DB_ARCH_REMOVE" class="olink">DB_ARCH_REMOVE</a> flag. 297 </p> 298 <p> 299 Note that if you are upgrading a replicated application, then you should 300 <span class="emphasis"><em>not</em></span> perform this step until all of the replication sites have been 301 upgraded to the current release level. If you run this site before all your sites are 302 upgraded, then errors can occur in your replication activities because important version 303 information might be lost. 304 </p> 305 </li> 306 <li> 307 <p> 308 Restart the application. 309 </p> 310 </li> 311 </ol> 312 </div> 313 <p> 314 Finally, Berkeley DB supports the live upgrade of a replication group, by allowing mixed version 315 operation (replication sites running at the newer software version can inter-operate with older 316 version sites). All client sites must be upgraded first; the master site must be upgraded last. 317 In other words, at all times the master must be running the lowest version of Berkeley DB. To 318 upgrade a replication group, you must: 319</p> 320 <div class="orderedlist"> 321 <ol type="1"> 322 <li> 323 <p> 324 Bring all clients up to date with the master (that is, all clients must be brought up to the 325 most current log record as measured by the master's log sequence number (LSN)). 326 </p> 327 </li> 328 <li> 329 <p> 330 Perform the upgrade procedures described previously on each of the individual database 331 environments that are part of the replication group. Each individual client may be upgraded 332 and restarted to join the replication group. 333 </p> 334 </li> 335 <li> 336 <p> 337 Shut down the master site and upgrade that site last. 338 </p> 339 </li> 340 </ol> 341 </div> 342 <p> 343 During live replication upgrade, while sites are running at different versions, adding new 344 (empty) clients to the replication group is not allowed. Those empty client environments must 345 be added after the entire group is upgraded. 346</p> 347 <p> 348 Also, all removal of log files must be suspended throughout this entire procedure, so that there 349 is no chance of a client needing internal initialization. 350</p> 351 <p> 352 Alternatively, it may be simpler to discard the contents of all of the client database 353 environments, upgrade the master database environment, and then re-add all of the clients to the 354 replication group using the standard replication procedures for new sites. 355</p> 356 </div> 357 <div class="navfooter"> 358 <hr /> 359 <table width="100%" summary="Navigation footer"> 360 <tr> 361 <td width="40%" align="left"><a accesskey="p" href="upgrade.html">Prev</a>��</td> 362 <td width="20%" align="center"> 363 <a accesskey="u" href="upgrade.html">Up</a> 364 </td> 365 <td width="40%" align="right">��<a accesskey="n" href="upgrade_2_0_toc.html">Next</a></td> 366 </tr> 367 <tr> 368 <td width="40%" align="left" valign="top">Chapter��31.�� 369 Upgrading from previous versions of Berkeley DB 370 ��</td> 371 <td width="20%" align="center"> 372 <a accesskey="h" href="index.html">Home</a> 373 </td> 374 <td width="40%" align="right" valign="top">��Chapter��32.��Upgrading Berkeley DB 1.85 or 1.86 applications to Berkeley DB 2.0</td> 375 </tr> 376 </table> 377 </div> 378 </body> 379</html> 380