1<!--$Id: intro.so,v 10.26 2006/11/13 18:05:04 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: Introduction to the transaction subsystem</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>Transaction Subsystem</dl></b></td> 14<td align=right><a href="/mp/config.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/txn/config.html"><img src="/images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Introduction to the transaction subsystem</b></p> 17<p>The Transaction subsystem makes operations atomic, consistent, isolated, 18and durable in the face of system and application failures. The subsystem 19requires that the data be properly logged and locked in order to attain 20these properties. Berkeley DB contains all the components necessary to 21transaction-protect the Berkeley DB access methods, and other forms of data may 22be protected if they are logged and locked appropriately.</p> 23<p>The Transaction subsystem is created, initialized, and opened by calls to 24<a href="/api_c/env_open.html">DB_ENV->open</a> with the <a href="/api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a> flag specified. Note 25that enabling transactions automatically enables logging, but does not 26enable locking because a single thread of control that needed atomicity 27and recoverability would not require it.</p> 28<p>The <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a> function starts a transaction, returning an opaque 29handle to a transaction. If the parent parameter to <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a> is 30non-NULL, the new transaction is a child of the designated parent 31transaction.</p> 32<p>The <a href="/api_c/txn_abort.html">DB_TXN->abort</a> function ends the designated transaction and causes 33all updates performed by the transaction to be undone. The end result is 34that the database is left in a state identical to the state that existed 35prior to the <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a>. If the aborting transaction has any child 36transactions associated with it (even ones that have already been 37committed), they are also aborted. Any transactions that are unresolved 38(neither committed nor aborted) when the application or system fails 39are aborted during recovery.</p> 40<p>The <a href="/api_c/txn_commit.html">DB_TXN->commit</a> function ends the designated transaction and makes 41all the updates performed by the transaction permanent, even in the face 42of application or system failure. If this is a parent transaction 43committing, all child transactions that individually committed or 44had not been resolved are also committed.</p> 45<p>Transactions are identified by 32-bit unsigned integers. The ID 46associated with any transaction can be obtained using the <a href="/api_c/txn_id.html">DB_TXN->id</a> 47function. If an application is maintaining information outside of Berkeley DB 48it wants to transaction-protect, it should use this transaction ID as 49the locking ID.</p> 50<p>The <a href="/api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> function causes a transaction checkpoint. A 51checkpoint is performed using to a specific log sequence number (LSN), 52referred to as the checkpoint LSN. When a checkpoint completes 53successfully, it means that all data buffers whose updates are described 54by LSNs less than the checkpoint LSN have been written to disk. This, in 55turn, means that the log records less than the checkpoint LSN are no 56longer necessary for normal recovery (although they would be required for 57catastrophic recovery if the database files were lost), and all log files 58containing only records prior to the checkpoint LSN may be safely archived 59and removed.</p> 60<p>The time required to run normal recovery is proportional to the amount 61of work done between checkpoints. If a large number of modifications 62happen between checkpoints, many updates recorded in the log may 63not have been written to disk when failure occurred, and recovery may 64take longer to run. Generally, if the interval between checkpoints is 65short, data may be being written to disk more frequently, but the 66recovery time will be shorter. Often, the checkpoint interval is tuned 67for each specific application.</p> 68<p>The <a href="/api_c/txn_stat.html">DB_ENV->txn_stat</a> method returns information about the status of the 69transaction subsystem. It is the programmatic interface used by the 70<a href="/utility/db_stat.html">db_stat</a> utility.</p> 71<p>The transaction system is closed by a call to <a href="/api_c/env_close.html">DB_ENV->close</a>.</p> 72<p>Finally, the entire transaction system may be removed using the 73<a href="/api_c/env_remove.html">DB_ENV->remove</a> method.</p> 74<!--$Id: m4.methods,v 1.6 2005/03/16 21:26:51 bostic Exp $--> 75<table border=1 align=center> 76<tr><th>Transaction Subsystem and Related Methods</th><th>Description</th></tr> 77<!--DbEnv::txn_checkpoint--><tr><td><a href="/api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a></td><td>Checkpoint the transaction subsystem</td></tr> 78<!--DbEnv::txn_recover--><tr><td><a href="/api_c/txn_recover.html">DB_ENV->txn_recover</a></td><td>Distributed transaction recovery</td></tr> 79<!--DbEnv::txn_stat--><tr><td><a href="/api_c/txn_stat.html">DB_ENV->txn_stat</a></td><td>Return transaction subsystem statistics</td></tr> 80<tr><th>Transaction Subsystem Configuration</th><th><br></th></tr> 81<!--DbEnv::set_timeout--><tr><td><a href="/api_c/env_set_timeout.html">DB_ENV->set_timeout</a></td><td>Set lock and transaction timeout</td></tr> 82<!--DbEnv::set_tx_max--><tr><td><a href="/api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a></td><td>Set maximum number of transactions</td></tr> 83<!--DbEnv::set_tx_timestamp--><tr><td><a href="/api_c/env_set_tx_timestamp.html">DB_ENV->set_tx_timestamp</a></td><td>Set recovery timestamp</td></tr> 84<tr><th>Transaction Operations</th><th><br></th></tr> 85<!--DbEnv::txn_begin--><tr><td><a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a></td><td>Begin a transaction</td></tr> 86<!--DbTxn::--> 87<!--DbTxn::abort--><tr><td><a href="/api_c/txn_abort.html">DB_TXN->abort</a></td><td>Abort a transaction</td></tr> 88<!--DbTxn::commit--><tr><td><a href="/api_c/txn_commit.html">DB_TXN->commit</a></td><td>Commit a transaction</td></tr> 89<!--DbTxn::discard--><tr><td><a href="/api_c/txn_discard.html">DB_TXN->discard</a></td><td>Discard a prepared but not resolved transaction handle</td></tr> 90<!--DbTxn::id--><tr><td><a href="/api_c/txn_id.html">DB_TXN->id</a></td><td>Return a transaction's ID</td></tr> 91<!--DbTxn::prepare--><tr><td><a href="/api_c/txn_prepare.html">DB_TXN->prepare</a></td><td>Prepare a transaction for commit</td></tr> 92<!--DbTxn::set_name--><tr><td><a href="/api_c/txn_set_name.html">DB_TXN->set_name</a></td><td>Associate a string with a transaction</td></tr> 93<!--DbTxn::set_timeout--><tr><td><a href="/api_c/txn_set_timeout.html">DB_TXN->set_timeout</a></td><td>Set transaction timeout</td></tr> 94</table> 95<table width="100%"><tr><td><br></td><td align=right><a href="/mp/config.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/txn/config.html"><img src="/images/next.gif" alt="Next"></a> 96</td></tr></table> 97<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 98</body> 99</html> 100
