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