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>Recovery Procedures</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="Getting Started with Berkeley DB Transaction Processing" /> 10 <link rel="up" href="filemanagement.html" title="Chapter��5.��Managing DB Files" /> 11 <link rel="prev" href="backuprestore.html" title="Backup Procedures" /> 12 <link rel="next" href="architectrecovery.html" title="Designing Your Application for Recovery" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Recovery Procedures</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="backuprestore.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��5.��Managing DB Files</th> 23 <td width="20%" align="right">��<a accesskey="n" href="architectrecovery.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="recovery"></a>Recovery Procedures</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="recovery.html#normalrecovery">Normal Recovery</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="recovery.html#catastrophicrecovery">Catastrophic Recovery</a> 46 </span> 47 </dt> 48 </dl> 49 </div> 50 <p> 51 DB supports two types of recovery: 52 </p> 53 <div class="itemizedlist"> 54 <ul type="disc"> 55 <li> 56 <p> 57 Normal recovery, which is run when your environment is 58 opened upon application startup, examines only those 59 log records needed to bring the databases to a consistent 60 state since the last checkpoint. Normal recovery 61 starts with any logs used by any transactions active at 62 the time of the last checkpoint, and examines all logs 63 from then to the current logs. 64 </p> 65 </li> 66 <li> 67 <p> 68 Catastrophic recovery, which is performed in the same 69 way that normal recovery is except that it examines 70 all available log files. You use catastrophic recovery 71 to restore your databases from a previously created backup. 72 </p> 73 </li> 74 </ul> 75 </div> 76 <p> 77 Of these two, normal recovery should be considered a routine 78 matter; in fact you should run normal 79 recovery whenever you start up your application. 80 </p> 81 <p> 82 Catastrophic recovery is run whenever you have lost or 83 corrupted your database files and you want to restore from a 84 backup. You also run catastrophic recovery when 85 you create a hot backup 86 (see <a class="xref" href="hotfailover.html" title="Using Hot Failovers">Using Hot Failovers</a> for more information). 87 </p> 88 <div class="sect2" lang="en" xml:lang="en"> 89 <div class="titlepage"> 90 <div> 91 <div> 92 <h3 class="title"><a id="normalrecovery"></a>Normal Recovery</h3> 93 </div> 94 </div> 95 </div> 96 <p> 97 Normal recovery examines the contents of your environment's 98 log files, and uses this information to ensure that your 99 database files are consistent relative to the 100 information contained in the log files. 101 </p> 102 <p> 103 Normal recovery also recreates your environment's region files. 104 This has the desired effect of clearing any unreleased locks 105 that your application may have held at the time of an 106 unclean application shutdown. 107 </p> 108 <p> 109 Normal recovery is run only against those log files created 110 since the time of your last checkpoint. For this reason, 111 your recovery time is dependent on how much data has been 112 written since the last checkpoint, and therefore on how 113 much log file information there is to examine. If you run 114 checkpoints infrequently, then normal recovery can 115 take a relatively long time. 116 </p> 117 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 118 <h3 class="title">Note</h3> 119 <p> 120 You should run normal recovery every 121 time you perform application startup. 122 </p> 123 </div> 124 <p> 125 To run normal recovery: 126 </p> 127 <div class="itemizedlist"> 128 <ul type="disc"> 129 <li> 130 <p> 131 Make sure all your environment handles are closed. 132 </p> 133 </li> 134 <li> 135 <p> 136 Normal recovery <span class="emphasis"><em>must 137 be</em></span> single-threaded. 138 </p> 139 </li> 140 <li> 141 <p> 142 Provide the <code class="literal">DB_RECOVER</code> flag when 143 you open your environment. 144 </p> 145 </li> 146 </ul> 147 </div> 148 <p> 149 You can also run recovery by pausing or shutting down your 150 application and using the <span class="command"><strong>db_recover</strong></span> 151 command line utility. 152 </p> 153 <p> 154 For example: 155 </p> 156 <pre class="programlisting">#include <stdio.h> 157#include <stdlib.h> 158#include "db.h" 159 160int 161main(void) 162{ 163 int ret; 164 u_int32_t env_flags; 165 DB_ENV *envp; 166 const char *db_home_dir = "/tmp/myEnvironment"; 167 168 envp = NULL; 169 170 /* Open the environment */ 171 ret = db_env_create(&envp, 0); 172 if (ret != 0) { 173 fprintf(stderr, "Error creating environment handle: %s\n", 174 db_strerror(ret)); 175 return (EXIT_FAILURE); 176 } 177 178 /* Open the environment, specifying that recovery is to be run. */ 179 env_flags = DB_CREATE | /* If the environment does not 180 * exist, create it. */ 181 DB_INIT_LOCK | /* Initialize locking */ 182 DB_INIT_LOG | /* Initialize logging */ 183 DB_INIT_MPOOL | /* Initialize the cache */ 184 DB_THREAD | /* Free-thread the env handle. */ 185 DB_INIT_TXN | /* Initialize transactions */ 186 DB_RECOVER; /* Run normal recovery */ 187 188 /* Open the environment. */ 189 ret = envp->open(envp, db_home_dir, env_flags, 0); 190 if (ret != 0) { 191 fprintf(stderr, "Error opening environment: %s\n", 192 db_strerror(ret)); 193 goto err; 194 } 195 196 ... 197 /* 198 * All other operations are identical from here. Notice, however, 199 * that we have not created any other threads of control before 200 * recovery is complete. You want to run recovery for 201 * the first thread in your application that opens an environment, 202 * but not for any subsequent threads. 203 */ </pre> 204 </div> 205 <div class="sect2" lang="en" xml:lang="en"> 206 <div class="titlepage"> 207 <div> 208 <div> 209 <h3 class="title"><a id="catastrophicrecovery"></a>Catastrophic Recovery</h3> 210 </div> 211 </div> 212 </div> 213 <p> 214 Use catastrophic recovery when you are 215 recovering your databases from a previously created backup. 216 Note that to restore your databases from a previous backup, you 217 should copy the backup to a new environment directory, and 218 then run catastrophic recovery. Failure to do so can lead to 219 the internal database structures being out of sync with your log files. 220 </p> 221 <p> 222 Catastrophic recovery must be run single-threaded. 223 </p> 224 <p> 225 To run catastrophic recovery: 226 </p> 227 <div class="itemizedlist"> 228 <ul type="disc"> 229 <li> 230 <p> 231 Shutdown all database operations. 232 </p> 233 </li> 234 <li> 235 <p> 236 Restore the backup to an empty directory. 237 </p> 238 </li> 239 <li> 240 <p> 241 Provide the <code class="literal">DB_RECOVER_FATAL</code> flag when 242 you open your environment. This environment open 243 must be single-threaded. 244 </p> 245 </li> 246 </ul> 247 </div> 248 <p> 249 You can also run recovery by pausing or shutting down your 250 application and using the <span class="command"><strong>db_recover</strong></span> 251 command line utility with the the <code class="literal">-c</code> option. 252 </p> 253 <p> 254 Note that catastrophic recovery examines every available 255 log file ��� not just those log files created since the 256 last checkpoint as is the case for normal recovery. For this reason, 257 catastrophic recovery is likely to take longer than does 258 normal recovery. 259 </p> 260 <p> 261 For example: 262 </p> 263 <pre class="programlisting">#include <stdio.h> 264#include <stdlib.h> 265#include "db.h" 266 267int 268main(void) 269{ 270 int ret; 271 u_int32_t env_flags; 272 DB_ENV *envp; 273 const char *db_home_dir = "/tmp/myEnvironment"; 274 275 envp = NULL; 276 277 /* Open the environment */ 278 ret = db_env_create(&envp, 0); 279 if (ret != 0) { 280 fprintf(stderr, "Error creating environment handle: %s\n", 281 db_strerror(ret)); 282 return (EXIT_FAILURE); 283 } 284 285 /* Open the environment, specifying that recovery is to be run. */ 286 env_flags = DB_CREATE | /* If the environment does not 287 * exist, create it. */ 288 DB_INIT_LOCK | /* Initialize locking */ 289 DB_INIT_LOG | /* Initialize logging */ 290 DB_INIT_MPOOL | /* Initialize the cache */ 291 DB_THREAD | /* Free-thread the env handle. */ 292 DB_INIT_TXN | /* Initialize transactions */ 293 <strong class="userinput"><code>DB_RECOVER_FATAL; /* Run catastrophic recovery */</code></strong> 294 295 /* Open the environment. */ 296 ret = envp->open(envp, db_home_dir, env_flags, 0); 297 if (ret != 0) { 298 fprintf(stderr, "Error opening environment: %s\n", 299 db_strerror(ret)); 300 goto err; 301 } 302 303 ... 304 /* 305 * All other operations are identical from here. Notice, however, 306 * that we have not created any other threads of control before 307 * recovery is complete. You want to run recovery for 308 * the first thread in your application that opens an environment, 309 * but not for any subsequent threads. 310 */ </pre> 311 </div> 312 </div> 313 <div class="navfooter"> 314 <hr /> 315 <table width="100%" summary="Navigation footer"> 316 <tr> 317 <td width="40%" align="left"><a accesskey="p" href="backuprestore.html">Prev</a>��</td> 318 <td width="20%" align="center"> 319 <a accesskey="u" href="filemanagement.html">Up</a> 320 </td> 321 <td width="40%" align="right">��<a accesskey="n" href="architectrecovery.html">Next</a></td> 322 </tr> 323 <tr> 324 <td width="40%" align="left" valign="top">Backup Procedures��</td> 325 <td width="20%" align="center"> 326 <a accesskey="h" href="index.html">Home</a> 327 </td> 328 <td width="40%" align="right" valign="top">��Designing Your Application for Recovery</td> 329 </tr> 330 </table> 331 </div> 332 </body> 333</html> 334