1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Chapter 18. The Transaction Subsystem</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 11 <link rel="prev" href="mp_config.html" title="Configuring the memory pool" /> 12 <link rel="next" href="txn_config.html" title="Configuring transactions" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 18. 19 The Transaction Subsystem 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="mp_config.html">Prev</a> </td> 24 <th width="60%" align="center"> </th> 25 <td width="20%" align="right"> <a accesskey="n" href="txn_config.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="chapter" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title"><a id="txn"></a>Chapter 18. 35 The Transaction Subsystem 36 </h2> 37 </div> 38 </div> 39 </div> 40 <div class="toc"> 41 <p> 42 <b>Table of Contents</b> 43 </p> 44 <dl> 45 <dt> 46 <span class="sect1"> 47 <a href="txn.html#txn_intro">Introduction to the transaction subsystem</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect1"> 52 <a href="txn_config.html">Configuring transactions</a> 53 </span> 54 </dt> 55 <dt> 56 <span class="sect1"> 57 <a href="txn_limits.html">Transaction limits</a> 58 </span> 59 </dt> 60 <dd> 61 <dl> 62 <dt> 63 <span class="sect2"> 64 <a href="txn_limits.html#id1625296">Transaction IDs</a> 65 </span> 66 </dt> 67 <dt> 68 <span class="sect2"> 69 <a href="txn_limits.html#id1624869">Cursors</a> 70 </span> 71 </dt> 72 <dt> 73 <span class="sect2"> 74 <a href="txn_limits.html#id1624849">Multiple Threads of Control</a> 75 </span> 76 </dt> 77 </dl> 78 </dd> 79 </dl> 80 </div> 81 <div class="sect1" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h2 class="title" style="clear: both"><a id="txn_intro"></a>Introduction to the transaction subsystem</h2> 86 </div> 87 </div> 88 </div> 89 <p>The Transaction subsystem makes operations atomic, consistent, isolated, 90and durable in the face of system and application failures. The subsystem 91requires that the data be properly logged and locked in order to attain 92these properties. Berkeley DB contains all the components necessary to 93transaction-protect the Berkeley DB access methods, and other forms of data may 94be protected if they are logged and locked appropriately.</p> 95 <p>The Transaction subsystem is created, initialized, and opened by calls to 96<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> with the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a> flag specified. Note 97that enabling transactions automatically enables logging, but does not 98enable locking because a single thread of control that needed atomicity 99and recoverability would not require it.</p> 100 <p>The <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> function starts a transaction, returning an opaque 101handle to a transaction. If the parent parameter to <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> is 102non-NULL, the new transaction is a child of the designated parent 103transaction.</p> 104 <p>The <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> function ends the designated transaction and causes 105all updates performed by the transaction to be undone. The end result is 106that the database is left in a state identical to the state that existed 107prior to the <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>. If the aborting transaction has any child 108transactions associated with it (even ones that have already been 109committed), they are also aborted. Any transactions that are unresolved 110(neither committed nor aborted) when the application or system fails 111are aborted during recovery.</p> 112 <p>The <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> function ends the designated transaction and makes 113all the updates performed by the transaction permanent, even in the face 114of application or system failure. If this is a parent transaction 115committing, all child transactions that individually committed or 116had not been resolved are also committed.</p> 117 <p>Transactions are identified by 32-bit unsigned integers. The ID 118associated with any transaction can be obtained using the <a href="../api_reference/C/txnid.html" class="olink">DB_TXN->id()</a> 119function. If an application is maintaining information outside of Berkeley DB 120it wants to transaction-protect, it should use this transaction ID as 121the locking ID.</p> 122 <p>The <a href="../api_reference/C/txncheckpoint.html" class="olink">DB_ENV->txn_checkpoint()</a> function causes a transaction checkpoint. A 123checkpoint is performed using to a specific log sequence number (LSN), 124referred to as the checkpoint LSN. When a checkpoint completes 125successfully, it means that all data buffers whose updates are described 126by LSNs less than the checkpoint LSN have been written to disk. This, in 127turn, means that the log records less than the checkpoint LSN are no 128longer necessary for normal recovery (although they would be required for 129catastrophic recovery if the database files were lost), and all log files 130containing only records prior to the checkpoint LSN may be safely archived 131and removed.</p> 132 <p>The time required to run normal recovery is proportional to the amount 133of work done between checkpoints. If a large number of modifications 134happen between checkpoints, many updates recorded in the log may 135not have been written to disk when failure occurred, and recovery may 136take longer to run. Generally, if the interval between checkpoints is 137short, data may be being written to disk more frequently, but the 138recovery time will be shorter. Often, the checkpoint interval is tuned 139for each specific application.</p> 140 <p>The <a href="../api_reference/C/txnstat.html" class="olink">DB_TXN->stat()</a> method returns information about the status of the 141transaction subsystem. It is the programmatic interface used by the 142<a href="../api_reference/C/db_stat.html" class="olink">db_stat utility</a>.</p> 143 <p>The transaction system is closed by a call to <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a>.</p> 144 <p>Finally, the entire transaction system may be removed using the 145<a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method.</p> 146 <div class="informaltable"> 147 <table border="1" width="80%"> 148 <colgroup> 149 <col /> 150 <col /> 151 </colgroup> 152 <thead> 153 <tr> 154 <th>Transaction Subsystem and Related Methods</th> 155 <th>Description</th> 156 </tr> 157 </thead> 158 <tbody> 159 <tr> 160 <td> 161 <a href="../api_reference/C/txncheckpoint.html" class="olink">DB_ENV->txn_checkpoint()</a> 162 </td> 163 <td>Checkpoint the transaction subsystem</td> 164 </tr> 165 <tr> 166 <td> 167 <a href="../api_reference/C/txnrecover.html" class="olink">DB_TXN->recover()</a> 168 </td> 169 <td>Distributed transaction recovery</td> 170 </tr> 171 <tr> 172 <td> 173 <a href="../api_reference/C/txnstat.html" class="olink">DB_TXN->stat()</a> 174 </td> 175 <td>Return transaction subsystem statistics</td> 176 </tr> 177 </tbody> 178 <tbody> 179 <tr> 180 <td> 181 <a href="../api_reference/C/envset_timeout.html" class="olink">DB_ENV->set_timeout()</a> 182 </td> 183 <td>Set lock and transaction timeout</td> 184 </tr> 185 <tr> 186 <td> 187 <a href="../api_reference/C/envset_tx_max.html" class="olink">DB_ENV->set_tx_max()</a> 188 </td> 189 <td>Set maximum number of transactions</td> 190 </tr> 191 <tr> 192 <td> 193 <a href="../api_reference/C/envset_tx_timestamp.html" class="olink">DB_ENV->set_tx_timestamp()</a> 194 </td> 195 <td>Set recovery timestamp</td> 196 </tr> 197 </tbody> 198 <tbody> 199 <tr> 200 <td> 201 <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> 202 </td> 203 <td>Begin a transaction</td> 204 </tr> 205 <tr> 206 <td> 207 <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> 208 </td> 209 <td>Abort a transaction</td> 210 </tr> 211 <tr> 212 <td> 213 <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> 214 </td> 215 <td>Commit a transaction</td> 216 </tr> 217 <tr> 218 <td> 219 <a href="../api_reference/C/txndiscard.html" class="olink">DB_TXN->discard()</a> 220 </td> 221 <td>Discard a prepared but not resolved transaction handle</td> 222 </tr> 223 <tr> 224 <td> 225 <a href="../api_reference/C/txnid.html" class="olink">DB_TXN->id()</a> 226 </td> 227 <td>Return a transaction's ID</td> 228 </tr> 229 <tr> 230 <td> 231 <a href="../api_reference/C/txnprepare.html" class="olink">DB_TXN->prepare()</a> 232 </td> 233 <td>Prepare a transaction for commit</td> 234 </tr> 235 <tr> 236 <td> 237 <a href="../api_reference/C/txnset_name.html" class="olink">DB_TXN->set_name()</a> 238 </td> 239 <td>Associate a string with a transaction</td> 240 </tr> 241 <tr> 242 <td> 243 <a href="../api_reference/C/txnset_timeout.html" class="olink">DB_TXN->set_timeout()</a> 244 </td> 245 <td>Set transaction timeout</td> 246 </tr> 247 </tbody> 248 </table> 249 </div> 250 </div> 251 </div> 252 <div class="navfooter"> 253 <hr /> 254 <table width="100%" summary="Navigation footer"> 255 <tr> 256 <td width="40%" align="left"><a accesskey="p" href="mp_config.html">Prev</a> </td> 257 <td width="20%" align="center"> </td> 258 <td width="40%" align="right"> <a accesskey="n" href="txn_config.html">Next</a></td> 259 </tr> 260 <tr> 261 <td width="40%" align="left" valign="top">Configuring the memory pool </td> 262 <td width="20%" align="center"> 263 <a accesskey="h" href="index.html">Home</a> 264 </td> 265 <td width="40%" align="right" valign="top"> Configuring transactions</td> 266 </tr> 267 </table> 268 </div> 269 </body> 270</html> 271