docs/programmer_reference/cam_fail.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>Handling failure in Data Store and Concurrent Data Store applications</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="Berkeley DB Programmer's Reference Guide" />
  10     <link rel="up" href="cam.html" title="Chapter 10.  Berkeley DB Concurrent Data Store Applications" />
  11     <link rel="prev" href="cam.html" title="Chapter 10.  Berkeley DB Concurrent Data Store Applications" />
  12     <link rel="next" href="cam_app.html" title="Architecting Data Store and Concurrent Data Store applications" />
  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">Handling failure in Data Store and Concurrent Data Store applications</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="cam.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 10.
  26                 Berkeley DB Concurrent Data Store Applications
  27         </th>
  28           <td width="20%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td>
  29         </tr>
  30       </table>
  31       <hr />
  32     </div>
  33     <div class="sect1" lang="en" xml:lang="en">
  34       <div class="titlepage">
  35         <div>
  36           <div>
  37             <h2 class="title" style="clear: both"><a id="cam_fail"></a>Handling failure in Data Store and Concurrent Data Store applications</h2>
  38           </div>
  39         </div>
  40       </div>
  41       <p>When building Data Store and Concurrent Data Store applications, there
  42 are design issues to consider whenever a thread of control with open
  43 Berkeley DB handles fails for any reason (where a thread of control may be
  44 either a true thread or a process).</p>
  45       <p>The simplest case is handling system failure for any Data Store or
  46 Concurrent Data Store application.  In the case of system failure, it
  47 doesn't matter if the application has opened a database environment or
  48 is just using standalone databases: if the system fails, after the
  49 application has modified a database and has not subsequently flushed the
  50 database to stable storage (by calling either the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a>,
  51 <a href="../api_reference/C/dbsync.html" class="olink">DB-&gt;sync()</a> or <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV-&gt;memp_sync()</a> methods), the database may be left in a
  52 corrupted state.  In this case, before accessing the database again, the
  53 database should either be:</p>
  54       <div class="itemizedlist">
  55         <ul type="disc">
  56           <li>removed and re-created,</li>
  57           <li>removed and restored from the last known good backup, or</li>
  58           <li>verified using the <a href="../api_reference/C/dbverify.html" class="olink">DB-&gt;verify()</a> method or <a href="../api_reference/C/db_verify.html" class="olink">db_verify</a> utility.  If
  59 the database does not verify cleanly, the contents may be salvaged using
  60 the <span class="bold"><strong>-R</strong></span> and <span class="bold"><strong>-r</strong></span> options of the <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility.</li>
  61         </ul>
  62       </div>
  63       <p>Applications where the potential for data loss is unacceptable should
  64 consider the Berkeley DB Transactional Data Store product, which offers standard transactional
  65 durability guarantees, including recoverability after failure.</p>
  66       <p>Additionally, system failure requires that any persistent database
  67 environment (that is, any database environment not created using the
  68 <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag), be removed.  Database environments may be
  69 removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> method.  If the persistent database
  70 environment was backed by the filesystem (that is, the environment was
  71 not created using the <a href="../api_reference/C/envopen.html#envopen_DB_SYSTEM_MEM" class="olink">DB_SYSTEM_MEM</a> flag), the database
  72 environment may also be safely removed by deleting the environment's
  73 files with standard system utilities.</p>
  74       <p>The second case is application failure for a Data Store application,
  75 with or without a database environment, or application failure for a
  76 Concurrent Data Store application without a database environment: as in
  77 the case of system failure, if any thread of control fails, after the
  78 application has modified a database and has not subsequently flushed the
  79 database to stable storage, the database may be left in a corrupted
  80 state.  In this case, the database should be handled as described
  81 previously in the system failure case.</p>
  82       <p>The third case is application failure for a Concurrent Data Store
  83 application with a database environment.  There are resources maintained
  84 in database environments that may be left locked if a thread of control
  85 exits without first closing all open Berkeley DB handles.  Concurrent Data
  86 Store applications with database environments have an additional option
  87 for handling the unexpected exit of a thread of control, the
  88 <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> method.</p>
  89       <p>The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> will return <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> if the
  90 database environment is unusable as a result of the thread of control
  91 failure.  (If a data structure mutex or a database write lock is left
  92 held by thread of control failure, the application should not continue
  93 to use the database environment, as subsequent use of the environment
  94 is likely to result in threads of control convoying behind the held
  95 locks.)  The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> call will release any database read
  96 locks that have been left held by the exit of a thread of control.  In
  97 this case, the application can continue to use the database
  98 environment.</p>
  99       <p>A Concurrent Data Store application recovering from a thread of control
 100 failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a>, and, if it returns success,
 101 the application can continue.  If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV-&gt;failchk()</a> returns
 102 <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, the application should proceed as described for
 103 the case of system failure.</p>
 104     </div>
 105     <div class="navfooter">
 106       <hr />
 107       <table width="100%" summary="Navigation footer">
 108         <tr>
 109           <td width="40%" align="left"><a accesskey="p" href="cam.html">Prev</a> </td>
 110           <td width="20%" align="center">
 111             <a accesskey="u" href="cam.html">Up</a>
 112           </td>
 113           <td width="40%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td>
 114         </tr>
 115         <tr>
 116           <td width="40%" align="left" valign="top">Chapter 10.
 117                 Berkeley DB Concurrent Data Store Applications
 118          </td>
 119           <td width="20%" align="center">
 120             <a accesskey="h" href="index.html">Home</a>
 121           </td>
 122           <td width="40%" align="right" valign="top"> Architecting Data Store and Concurrent Data Store applications</td>
 123         </tr>
 124       </table>
 125     </div>
 126   </body>
 127 </html>