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