diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/transapp_faq.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/transapp_faq.html')
| -rw-r--r-- | docs/programmer_reference/transapp_faq.html | 271 |
1 files changed, 146 insertions, 125 deletions
diff --git a/docs/programmer_reference/transapp_faq.html b/docs/programmer_reference/transapp_faq.html index f2e0b872..86d8a540 100644 --- a/docs/programmer_reference/transapp_faq.html +++ b/docs/programmer_reference/transapp_faq.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </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> + <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> @@ -42,145 +40,169 @@ <ol type="1"> <li> <p> - <span class="bold"><strong>What should a transactional program do when an error occurs?</strong></span> - </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> + 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> + <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> + 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> + <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> + 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> + 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> + <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> + </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> + <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> + <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> + 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> @@ -196,13 +218,12 @@ are less prone to deadlock than <a href="../api_reference/C/dbopen.html#dbopen_D <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="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> + <td width="40%" align="right" valign="top"> Chapter 12. Berkeley DB Replication </td> </tr> </table> </div> |