1<!--$Id: filesys.so,v 10.35 2002/02/05 18:34:09 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: Recovery and filesystem operations</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<a name="2"><!--meow--></a>
12<table width="100%"><tr valign=top>
13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></b></td>
14<td align=right><a href="/transapp/hotfail.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/reclimit.html"><img src="/images/next.gif" alt="Next"></a>
15</td></tr></table>
16<p align=center><b>Recovery and filesystem operations</b></p>
17<p>The Berkeley DB API supports creating, removing and renaming files.  Creating
18files is supported by the <a href="/api_c/db_open.html">DB-&gt;open</a> method.  Removing files is
19supported by the <a href="/api_c/env_dbremove.html">DB_ENV-&gt;dbremove</a> and <a href="/api_c/db_remove.html">DB-&gt;remove</a> methods.
20Renaming files is supported by the <a href="/api_c/env_dbrename.html">DB_ENV-&gt;dbrename</a> and
21<a href="/api_c/db_rename.html">DB-&gt;rename</a> methods.  (There are two methods for removing and renaming
22files because one of the methods is transactionally protected and one
23is not.)</p>
24<p>Berkeley DB does not permit specifying the <a href="/api_c/db_open.html#DB_TRUNCATE">DB_TRUNCATE</a> flag when
25opening a file in a transaction-protected environment.  This is an
26implicit file deletion, but one that does not always require the same
27operating system file permissions as deleting and creating a file do.</p>
28<p>If you have changed the name of a file or deleted it outside of the
29Berkeley DB library (for example, you explicitly removed a file using your
30normal operating system utilities), then it is possible that recovery
31will not be able to find a database to which the log refers.  In this
32case, <a href="/utility/db_recover.html">db_recover</a> will produce a warning message, saying it was
33unable to locate a file it expected to find.  This message is only a
34warning because the file may have been subsequently deleted as part of
35normal database operations before the failure occurred, so is not
36necessarily a problem.</p>
37<p>Generally, any filesystem operations that are performed outside the
38Berkeley DB interface should be performed at the same time as making a
39snapshot of the database.  To perform filesystem operations correctly,
40do the following:</p>
41<ol>
42<p><li>Cleanly shut down database operations.
43<p>To shut down database operations cleanly, all applications accessing
44the database environment must be shut down and a transaction checkpoint
45must be taken.  If the applications are not implemented so they can be
46shut down gracefully (that is, closing all references to the database
47environment), recovery must be performed after all applications have
48been killed to ensure that the underlying databases are consistent on
49disk.</p>
50<p><li>Perform the filesystem operations; for example, remove or rename one or
51more files.
52<p><li>Make an archival snapshot of the database.
53<p>Although this step is not strictly necessary, it is strongly
54recommended.  If this step is not performed, recovery from catastrophic
55failure will require that recovery first be performed up to the time of
56the filesystem operations, the filesystem operations be redone, and then
57recovery be performed from the filesystem operations forward.</p>
58<p><li>Restart the database applications.
59</ol>
60<table width="100%"><tr><td><br></td><td align=right><a href="/transapp/hotfail.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/reclimit.html"><img src="/images/next.gif" alt="Next"></a>
61</td></tr></table>
62<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
63</body>
64</html>
65