1<!--$Id: fail.so,v 10.2 2005/10/19 21:10:31 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Handling failure in Data Store and Concurrent Data Store applications</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Concurrent Data Store Applications</dl></b></td> 13<td align=right><a href="../cam/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../cam/app.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Handling failure in Data Store and Concurrent Data Store applications</b></p> 16<p>When building Data Store and Concurrent Data Store applications, there 17are design issues to consider whenever a thread of control with open 18Berkeley DB handles fails for any reason (where a thread of control may be 19either a true thread or a process).</p> 20<p>The simplest case is handling system failure for any Data Store or 21Concurrent Data Store application. In the case of system failure, it 22doesn't matter if the application has opened a database environment or 23is just using standalone databases: if the system fails, after the 24application has modified a database and has not subsequently flushed the 25database to stable storage (by calling either the <a href="../../api_c/db_close.html">DB->close</a>, 26<a href="../../api_c/db_sync.html">DB->sync</a> or <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> methods), the database may be left in a 27corrupted state. In this case, before accessing the database again, the 28database should either be:</p> 29<p><ul type=disc> 30<li>removed and re-created, 31<li>removed and restored from the last known good backup, or 32<li>verified using the <a href="../../api_c/db_verify.html">DB->verify</a> method or <a href="../../utility/db_verify.html">db_verify</a> utility. If 33the database does not verify cleanly, the contents may be salvaged using 34the <b>-R</b> and <b>-r</b> options of the <a href="../../utility/db_dump.html">db_dump</a> 35utility. 36</ul> 37<p>Applications where the potential for data loss is unacceptable should 38consider the Berkeley DB Transactional Data Store product, which offers standard transactional 39durability guarantees, including recoverability after failure.</p> 40<p>Additionally, system failure requires that any persistent database 41environment (that is, any database environment not created using the 42<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag), be removed. Database environments may be 43removed using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method. If the persistent database 44environment was backed by the filesystem (that is, the environment was 45not created using the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag), the database 46environment may also be safely removed by deleting the environment's 47files with standard system utilities.</p> 48<p>The second case is application failure for a Data Store application, 49with or without a database environment, or application failure for a 50Concurrent Data Store application without a database environment: as in 51the case of system failure, if any thread of control fails, after the 52application has modified a database and has not subsequently flushed the 53database to stable storage, the database may be left in a corrupted 54state. In this case, the database should be handled as described 55previously in the system failure case.</p> 56<p>The third case is application failure for a Concurrent Data Store 57application with a database environment. There are resources maintained 58in database environments that may be left locked if a thread of control 59exits without first closing all open Berkeley DB handles. Concurrent Data 60Store applications with database environments have an additional option 61for handling the unexpected exit of a thread of control, the 62<a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method.</p> 63<p>The <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method will return <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> if the 64database environment is unusable as a result of the thread of control 65failure. (If a data structure mutex or a database write lock is left 66held by thread of control failure, the application should not continue 67to use the database environment, as subsequent use of the environment 68is likely to result in threads of control convoying behind the held 69locks.) The <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> call will release any database read 70locks that have been left held by the exit of a thread of control. In 71this case, the application can continue to use the database 72environment.</p> 73<p>A Concurrent Data Store application recovering from a thread of control 74failure should call <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a>, and, if it returns success, 75the application can continue. If <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> returns 76<a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, the application should proceed as described for 77the case of system failure.</p> 78<table width="100%"><tr><td><br></td><td align=right><a href="../cam/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../cam/app.html"><img src="../../images/next.gif" alt="Next"></a> 79</td></tr></table> 80<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 81</body> 82</html> 83