1<!--$Id: faq.so,v 10.11 2006/05/09 19:46:59 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: Transaction FAQ</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/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/intro.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Transaction FAQ</b></p> 17<ol> 18<p><li><b>What should a transactional program do when an error occurs?</b> 19<p>Any time an error occurs, such that a transactionally protected set of 20operations cannot complete successfully, the transaction must be 21aborted. While deadlock is by far the most common of these errors, 22there are other possibilities; for example, running out of disk space 23for the filesystem. In Berkeley DB transactional applications, there are 24three classes of error returns: "expected" errors, "unexpected but 25recoverable" errors, and a single "unrecoverable" error. Expected 26errors are errors like <a href="../../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>, which indicates that a 27searched-for key item is not present in the database. Applications may 28want to explicitly test for and handle this error, or, in the case where 29the absence of a key implies the enclosing transaction should fail, 30simply call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a>. Unexpected but recoverable errors are 31errors like <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates that an operation 32has been selected to resolve a deadlock, or a system error such as EIO, 33which likely indicates that the filesystem has no available disk space. 34Applications must immediately call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> when these returns 35occur, as it is not possible to proceed otherwise. The only 36unrecoverable error is <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, which indicates that the 37system must stop and recovery must be run.</p> 38<p><li><b>How can hot backups work? Can't you get an inconsistent picture 39of the database when you copy it?</b> 40<p>First, Berkeley DB is based on the technique of "write-ahead logging", which 41means that before any change is made to a database, a log record is 42written that describes the change. Further, Berkeley DB guarantees that the 43log record that describes the change will always be written to stable 44storage (that is, disk) before the database page where the change was 45made is written to stable storage. Because of this guarantee, we know 46that any change made to a database will appear either in just a log 47file, or both the database and a log file, but never in just the 48database.</p> 49<p>Second, you can always create a consistent and correct database based 50on the log files and the databases from a database environment. So, 51during a hot backup, we first make a copy of the databases and then a 52copy of the log files. The tricky part is that there may be pages in 53the database that are related for which we won't get a consistent 54picture during this copy. For example, let's say that we copy pages 551-4 of the database, and then are swapped out. For whatever reason 56(perhaps because we needed to flush pages from the cache, or because of 57a checkpoint), the database pages 1 and 5 are written. Then, the hot 58backup process is re-scheduled, and it copies page 5. Obviously, we 59have an inconsistent database snapshot, because we have a copy of page 601 from before it was written by the other thread of control, and a copy 61of page 5 after it was written by the other thread. What makes this 62work is the order of operations in a hot backup. Because of the 63write-ahead logging guarantees, we know that any page written to the 64database will first be referenced in the log. If we copy the database 65first, then we can also know that any inconsistency in the database will 66be described in the log files, and so we know that we can fix everything 67up during recovery.</p> 68<p><li><b>My application has <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> errors. Is the 69normal, and what should I do?</b> 70<p>It is quite rare for a transactional application to be deadlock free. 71All applications should be prepared to handle deadlock returns, because 72even if the application is deadlock free when deployed, future changes 73to the application or the Berkeley DB implementation might introduce 74deadlocks.</p> 75<p>Practices which reduce the chance of deadlock include: 76<p><ul type=disc> 77<li>Not using cursors which move backwards through the database (<a href="../../api_c/dbc_get.html#DB_PREV">DB_PREV</a>), 78as backward scanning cursors can deadlock with page splits; 79<li>Configuring <a href="../../api_c/db_set_flags.html#DB_REVSPLITOFF">DB_REVSPLITOFF</a> to turn off reverse splits in 80applications which repeatedly delete and re-insert the same keys, to 81minimize the number of page splits as keys are re-inserted; 82<li>Not configuring <a href="../../api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> as that flag requires write 83transactions upgrade their locks when aborted, which can lead to deadlock. 84Generally, <a href="../../api_c/db_cursor.html#DB_READ_COMMITTED">DB_READ_COMMITTED</a> or non-transactional read operations 85are less prone to deadlock than <a href="../../api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a>. 86</ul></p> 87<p><li><b>How can I move a database from one transactional environment 88into another?</b> 89<p>Because database pages contain references to log records, databases 90cannot be simply moved into different database environments. To move a 91database into a different environment, dump and reload the database 92before moving it. If the database is too large to dump and reload, the 93database may be prepared in place using the <a href="../../api_c/env_lsn_reset.html">DB_ENV->lsn_reset</a> method or 94the <b>-r</b> argument to the <a href="../../utility/db_load.html">db_load</a> utility.</p> 95<p><li><b>I'm seeing the error "log_flush: LSN past current end-of-log", 96what does that mean?</b> 97<p>The most common cause of this error is that a system administrator has 98removed all of the log files from a database environment. You should 99shut down your database environment as gracefully as possible, first 100flushing the database environment cache to disk, if that's possible. 101Then, dump and reload your databases. If the database is too large to 102dump and reload, the database may be reset in place using the 103<a href="../../api_c/env_lsn_reset.html">DB_ENV->lsn_reset</a> method or the <b>-r</b> argument to the 104<a href="../../utility/db_load.html">db_load</a> utility. However, if you 105reset the database in place, you should verify your databases before 106using them again. (It is possible for the databases to be corrupted by 107running after all of the log files have been removed, and the longer the 108application runs, the worse it can get.)</p> 109</ol> 110<table width="100%"><tr><td><br></td><td align=right><a href="../transapp/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rep/intro.html"><img src="../../images/next.gif" alt="Next"></a> 111</td></tr></table> 112<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 113</body> 114</html> 115