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 Specify <code class="literal">true</code> to 143 <code class="methodname">EnvironmentConfig.setRunRecovery()</code> 144 when you open your environment. 145 </p> 146 </li> 147 </ul> 148 </div> 149 <p> 150 You can also run recovery by pausing or shutting down your 151 application and using the <span class="command"><strong>db_recover</strong></span> 152 command line utility. 153 </p> 154 <p> 155 For example: 156 </p> 157 <pre class="programlisting">package db.txn; 158 159import com.sleepycat.db.DatabaseException; 160import com.sleepycat.db.Environment; 161import com.sleepycat.db.EnvironmentConfig; 162 163import java.io.File; 164import java.io.FileNotFoundException; 165 166 167... 168 169 170Environment myEnv = null; 171try { 172 EnvironmentConfig myEnvConfig = new EnvironmentConfig(); 173 myEnvConfig.setInitializeCache(true); 174 myEnvConfig.setInitializeLocking(true); 175 myEnvConfig.setInitializeLogging(true); 176 myEnvConfig.setTransactional(true); 177 178 // Run normal recovery 179 myEnvConfig.setRunRecovery(true); 180 181 myEnv = new Environment(new File("/my/env/home"), 182 myEnvConfig); 183 184 // All other operations are identical from here. Notice, however, 185 // that we have not created any other threads of control before 186 // recovery is complete. You want to run recovery for 187 // the first thread in your application that opens an environment, 188 // but not for any subsequent threads. 189 190} catch (DatabaseException de) { 191 // Exception handling goes here 192} catch (FileNotFoundException fnfe) { 193 // Exception handling goes here 194}</pre> 195 </div> 196 <div class="sect2" lang="en" xml:lang="en"> 197 <div class="titlepage"> 198 <div> 199 <div> 200 <h3 class="title"><a id="catastrophicrecovery"></a>Catastrophic Recovery</h3> 201 </div> 202 </div> 203 </div> 204 <p> 205 Use catastrophic recovery when you are 206 recovering your databases from a previously created backup. 207 Note that to restore your databases from a previous backup, you 208 should copy the backup to a new environment directory, and 209 then run catastrophic recovery. Failure to do so can lead to 210 the internal database structures being out of sync with your log files. 211 </p> 212 <p> 213 Catastrophic recovery must be run single-threaded. 214 </p> 215 <p> 216 To run catastrophic recovery: 217 </p> 218 <div class="itemizedlist"> 219 <ul type="disc"> 220 <li> 221 <p> 222 Shutdown all database operations. 223 </p> 224 </li> 225 <li> 226 <p> 227 Restore the backup to an empty directory. 228 </p> 229 </li> 230 <li> 231 <p> 232 Specify <code class="literal">true</code> to 233 <code class="methodname">EnvironmentConfig.setRunRecoveryFatal()</code> 234 when you open your environment. This environment 235 open must be single-threaded. 236 </p> 237 </li> 238 </ul> 239 </div> 240 <p> 241 You can also run recovery by pausing or shutting down your 242 application and using the <span class="command"><strong>db_recover</strong></span> 243 command line utility with the the <code class="literal">-c</code> option. 244 </p> 245 <p> 246 Note that catastrophic recovery examines every available 247 log file — not just those log files created since the 248 last checkpoint as is the case for normal recovery. For this reason, 249 catastrophic recovery is likely to take longer than does 250 normal recovery. 251 </p> 252 <p> 253 For example: 254 </p> 255 <pre class="programlisting">package db.txn; 256 257import com.sleepycat.db.DatabaseException; 258import com.sleepycat.db.Environment; 259import com.sleepycat.db.EnvironmentConfig; 260 261import java.io.File; 262import java.io.FileNotFoundException; 263 264 265... 266 267 268Environment myEnv = null; 269try { 270 EnvironmentConfig myEnvConfig = new EnvironmentConfig(); 271 myEnvConfig.setInitializeCache(true); 272 myEnvConfig.setInitializeLocking(true); 273 myEnvConfig.setInitializeLogging(true); 274 myEnvConfig.setTransactional(true); 275 276 // Run catastrophic recovery 277 <strong class="userinput"><code>myEnvConfig.setRunFatalRecovery(true);</code></strong> 278 279 myEnv = new Environment(new File("/my/env/home"), 280 myEnvConfig); 281 282} catch (DatabaseException de) { 283 // Exception handling goes here 284} catch (FileNotFoundException fnfe) { 285 // Exception handling goes here 286}</pre> 287 </div> 288 </div> 289 <div class="navfooter"> 290 <hr /> 291 <table width="100%" summary="Navigation footer"> 292 <tr> 293 <td width="40%" align="left"><a accesskey="p" href="backuprestore.html">Prev</a> </td> 294 <td width="20%" align="center"> 295 <a accesskey="u" href="filemanagement.html">Up</a> 296 </td> 297 <td width="40%" align="right"> <a accesskey="n" href="architectrecovery.html">Next</a></td> 298 </tr> 299 <tr> 300 <td width="40%" align="left" valign="top">Backup Procedures </td> 301 <td width="20%" align="center"> 302 <a accesskey="h" href="index.html">Home</a> 303 </td> 304 <td width="40%" align="right" valign="top"> Designing Your Application for Recovery</td> 305 </tr> 306 </table> 307 </div> 308 </body> 309</html> 310