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 "db_cxx.h" 157 158... 159 160void *checkpoint_thread(void *); 161 162int main(void) 163{ 164 u_int32_t env_flags = DB_CREATE | // If the environment does not 165 // exist, create it. 166 DB_INIT_LOCK | // Initialize locking 167 DB_INIT_LOG | // Initialize logging 168 DB_INIT_MPOOL | // Initialize the cache 169 DB_INIT_TXN | // Initialize transactions 170 DB_THREAD | // Free-thread the env handle 171 DB_RECOVER; // Run normal recovery 172 173 std::string envHome("/export1/testEnv"); 174 DbEnv myEnv(0); 175 176 try { 177 178 myEnv.open(envHome.c_str(), env_flags, 0); 179 180 ... 181 182 // All other operations are identical from here. Notice, however, 183 // that we have not created any other threads of control before 184 // recovery is complete. You want to run recovery for 185 // the first thread in your application that opens an environment, 186 // but not for any subsequent threads. </pre> 187 </div> 188 <div class="sect2" lang="en" xml:lang="en"> 189 <div class="titlepage"> 190 <div> 191 <div> 192 <h3 class="title"><a id="catastrophicrecovery"></a>Catastrophic Recovery</h3> 193 </div> 194 </div> 195 </div> 196 <p> 197 Use catastrophic recovery when you are 198 recovering your databases from a previously created backup. 199 Note that to restore your databases from a previous backup, you 200 should copy the backup to a new environment directory, and 201 then run catastrophic recovery. Failure to do so can lead to 202 the internal database structures being out of sync with your log files. 203 </p> 204 <p> 205 Catastrophic recovery must be run single-threaded. 206 </p> 207 <p> 208 To run catastrophic recovery: 209 </p> 210 <div class="itemizedlist"> 211 <ul type="disc"> 212 <li> 213 <p> 214 Shutdown all database operations. 215 </p> 216 </li> 217 <li> 218 <p> 219 Restore the backup to an empty directory. 220 </p> 221 </li> 222 <li> 223 <p> 224 Provide the <code class="literal">DB_RECOVER_FATAL</code> flag when 225 you open your environment. This environment open 226 must be single-threaded. 227 </p> 228 </li> 229 </ul> 230 </div> 231 <p> 232 You can also run recovery by pausing or shutting down your 233 application and using the <span class="command"><strong>db_recover</strong></span> 234 command line utility with the the <code class="literal">-c</code> option. 235 </p> 236 <p> 237 Note that catastrophic recovery examines every available 238 log file — not just those log files created since the 239 last checkpoint as is the case for normal recovery. For this reason, 240 catastrophic recovery is likely to take longer than does 241 normal recovery. 242 </p> 243 <p> 244 For example: 245 </p> 246 <pre class="programlisting">#include "db_cxx.h" 247 248... 249 250void *checkpoint_thread(void *); 251 252int main(void) 253{ 254 u_int32_t env_flags = DB_CREATE | // If the environment does not 255 // exist, create it. 256 DB_INIT_LOCK | // Initialize locking 257 DB_INIT_LOG | // Initialize logging 258 DB_INIT_MPOOL | // Initialize the cache 259 DB_INIT_TXN | // Initialize transactions 260 DB_THREAD | // Free-thread the env handle 261 <strong class="userinput"><code>DB_RECOVER_FATAL; // Run catastrophic recovery</code></strong> 262 263 std::string envHome("/export1/testEnv"); 264 DbEnv myEnv(0); 265 266 try { 267 268 myEnv.open(envHome.c_str(), env_flags, 0); 269 270 ... 271 272 // All other operations are identical from here. Notice, however, 273 // that we have not created any other threads of control before 274 // recovery is complete. You want to run recovery for 275 // the first thread in your application that opens an environment, 276 // but not for any subsequent threads. </pre> 277 </div> 278 </div> 279 <div class="navfooter"> 280 <hr /> 281 <table width="100%" summary="Navigation footer"> 282 <tr> 283 <td width="40%" align="left"><a accesskey="p" href="backuprestore.html">Prev</a> </td> 284 <td width="20%" align="center"> 285 <a accesskey="u" href="filemanagement.html">Up</a> 286 </td> 287 <td width="40%" align="right"> <a accesskey="n" href="architectrecovery.html">Next</a></td> 288 </tr> 289 <tr> 290 <td width="40%" align="left" valign="top">Backup Procedures </td> 291 <td width="20%" align="center"> 292 <a accesskey="h" href="index.html">Home</a> 293 </td> 294 <td width="40%" align="right" valign="top"> Designing Your Application for Recovery</td> 295 </tr> 296 </table> 297 </div> 298 </body> 299</html> 300