docs/gsg_txn/CXX/recovery.html

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