mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 09:06:25 +00:00
210 lines
11 KiB
HTML
210 lines
11 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Transaction FAQ</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="transapp.html" title="Chapter 11. Berkeley DB Transactional Data Store Applications" />
|
||
<link rel="prev" href="transapp_throughput.html" title="Transaction throughput" />
|
||
<link rel="next" href="rep.html" title="Chapter 12. Berkeley DB Replication" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Transaction FAQ</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="transapp_throughput.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 11.
|
||
Berkeley DB Transactional Data Store Applications
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="rep.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="transapp_faq"></a>Transaction FAQ</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>What should a transactional program do when an error occurs?</strong></span>
|
||
</p>
|
||
<p>
|
||
Any time an error occurs, such that a transactionally protected
|
||
set of operations cannot complete successfully, the transaction
|
||
must be aborted. While deadlock is by far the most common of
|
||
these errors, there are other possibilities; for example,
|
||
running out of disk space for the filesystem. In Berkeley DB
|
||
transactional applications, there are three classes of error
|
||
returns: "expected" errors, "unexpected but recoverable"
|
||
errors, and a single "unrecoverable" error. Expected errors
|
||
are errors like
|
||
<a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a>,
|
||
which indicates that a searched-for key item is not present in
|
||
the database. Applications may want to explicitly test for and
|
||
handle this error, or, in the case where the absence of a key
|
||
implies the enclosing transaction should fail, simply call
|
||
<a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>. Unexpected but recoverable errors are errors like
|
||
<a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>,
|
||
which indicates that an operation has been selected to resolve
|
||
a deadlock, or a system error such as EIO, which likely
|
||
indicates that the filesystem has no available disk space.
|
||
Applications must immediately call <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> when these
|
||
returns occur, as it is not possible to proceed otherwise. The
|
||
only unrecoverable error is
|
||
<a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>,
|
||
which indicates that the system must stop and recovery must be
|
||
run.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>How can hot backups work? Can't you get an
|
||
inconsistent picture of the database when you copy
|
||
it?</strong></span>
|
||
</p>
|
||
<p>
|
||
First, Berkeley DB is based on the technique of "write-ahead
|
||
logging", which means that before any change is made to a
|
||
database, a log record is written that describes the change.
|
||
Further, Berkeley DB guarantees that the log record that
|
||
describes the change will always be written to stable storage
|
||
(that is, disk) before the database page where the change was
|
||
made is written to stable storage. Because of this guarantee,
|
||
we know that any change made to a database will appear either
|
||
in just a log file, or both the database and a log file, but
|
||
never in just the database.
|
||
</p>
|
||
<p>
|
||
Second, you can always create a consistent and correct database
|
||
based on the log files and the databases from a database
|
||
environment. So, during a hot backup, we first make a copy of
|
||
the databases and then a copy of the log files. The tricky
|
||
part is that there may be pages in the database that are
|
||
related for which we won't get a consistent picture during this
|
||
copy. For example, let's say that we copy pages 1-4 of the
|
||
database, and then are swapped out. For whatever reason
|
||
(perhaps because we needed to flush pages from the cache, or
|
||
because of a checkpoint), the database pages 1 and 5 are
|
||
written. Then, the hot backup process is re-scheduled, and it
|
||
copies page 5. Obviously, we have an inconsistent database
|
||
snapshot, because we have a copy of page 1 from before it was
|
||
written by the other thread of control, and a copy of page 5
|
||
after it was written by the other thread. What makes this work
|
||
is the order of operations in a hot backup. Because of the
|
||
write-ahead logging guarantees, we know that any page written
|
||
to the database will first be referenced in the log. If we
|
||
copy the database first, then we can also know that any
|
||
inconsistency in the database will be described in the log
|
||
files, and so we know that we can fix everything up during
|
||
recovery.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>My application has <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>
|
||
errors. Is the normal, and what should I do?</strong></span>
|
||
</p>
|
||
<p>
|
||
It is quite rare for a transactional application to be deadlock
|
||
free. All applications should be prepared to handle deadlock
|
||
returns, because even if the application is deadlock free when
|
||
deployed, future changes to the application or the Berkeley DB
|
||
implementation might introduce deadlocks.
|
||
</p>
|
||
<p>
|
||
Practices which reduce the chance of deadlock include:
|
||
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>Not using cursors which move backwards through the database (<a href="../api_reference/C/dbcget.html#dbcget_DB_PREV" class="olink">DB_PREV</a>),
|
||
as backward scanning cursors can deadlock with page splits;</li>
|
||
<li>Configuring <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_REVSPLITOFF" class="olink">DB_REVSPLITOFF</a> to turn off reverse splits in
|
||
applications which repeatedly delete and re-insert the same keys, to
|
||
minimize the number of page splits as keys are re-inserted;</li>
|
||
<li>Not configuring <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> as that flag requires write
|
||
transactions upgrade their locks when aborted, which can lead to deadlock.
|
||
Generally, <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or non-transactional read operations
|
||
are less prone to deadlock than <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a>.</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>How can I move a database from one
|
||
transactional environment into another?</strong></span>
|
||
</p>
|
||
<p>
|
||
Because database pages contain references to log records,
|
||
databases cannot be simply moved into different database
|
||
environments. To move a database into a different environment,
|
||
dump and reload the database before moving it. If the database
|
||
is too large to dump and reload, the database may be prepared
|
||
in place using the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV->lsn_reset()</a> method or the <span class="bold"><strong>-r</strong></span> argument to the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>I'm seeing the error "log_flush: LSN past
|
||
current end-of-log", what does that mean?</strong></span>
|
||
</p>
|
||
<p>
|
||
The most common cause of this error is that a system
|
||
administrator has removed all of the log files from a database
|
||
environment. You should shut down your database environment as
|
||
gracefully as possible, first flushing the database environment
|
||
cache to disk, if that's possible. Then, dump and reload your
|
||
databases. If the database is too large to dump and reload,
|
||
the database may be reset in place using the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV->lsn_reset()</a>
|
||
method or the <span class="bold"><strong>-r</strong></span> argument to
|
||
the <a href="../api_reference/C/db_load.html" class="olink">db_load</a> utility. However, if you reset the database in place,
|
||
you should verify your databases before using them again. (It
|
||
is possible for the databases to be corrupted by running after
|
||
all of the log files have been removed, and the longer the
|
||
application runs, the worse it can get.)
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="transapp_throughput.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="transapp.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="rep.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Transaction throughput </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Chapter 12.
|
||
Berkeley DB Replication
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|