NNAAMMEE DbTxn - Db transaction management SSYYNNOOPPSSIISS ##iinncclluuddee <> iinntt DDbbTTxxnn::::pprreeppaarree(());; iinntt DDbbTTxxnn::::ccoommmmiitt(());; iinntt DDbbTTxxnn::::aabboorrtt(());; uu__iinntt3322__tt DDbbTTxxnn::::iidd(());; DDEESSCCRRIIPPTTIIOONN The DB library is a family of classes that provides a mod- ular programming interface to transactions and record-ori- ented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the classes (e.g., the file page caching class) are useful independent of the other DB classes, although some classes are explicitly based on other classes (e.g., transactions and logging). For a general description of the DB pack- age, see _d_b___i_n_t_r_o(3). This manual page describes the specific details of the Db transaction support. The DbTxn class is used in conjunc- tion with _D_b_T_x_n_M_g_r(3) to provide transaction semantics. Full transaction support is provided by a collection of modules that provide interfaces to the services required for transaction processing. These services are recovery (see _D_b_L_o_g(3)), concurrency control (see _D_b_L_o_c_k(3) and _D_b_L_o_c_k_T_a_b(3)), and the management of shared data (see _D_b_M_- _p_o_o_l(3) and _D_b_M_p_o_o_l_F_i_l_e(3)). Transaction semantics can be applied to the access methods described in _D_b(3) through method call parameters. The model intended for transactional use (and the one that is used by the access methods) is write-ahead logging pro- vided by _D_b_L_o_g(3) to record both before- and after-images. Locking follows a two-phase protocol, with all locks being released at transaction commit. _D_b_T_x_n_:_:_p_r_e_p_a_r_e The _D_b_T_x_n_:_:_p_r_e_p_a_r_e method initiates the beginning of a two phase commit. In a distributed transaction environment, _d_b can be used as a local transaction manager. In this case, the distributed transaction manager must send _p_r_e_- _p_a_r_e messages to each local manager. The local manager must then issue a _D_b_T_x_n_:_:_p_r_e_p_a_r_e and await its successful return before responding to the distributed transaction manager. Only after the distributed transaction manager receives successful responses from all of its _p_r_e_p_a_r_e messages should it issue any _c_o_m_m_i_t messages. The _D_b_T_x_n_:_:_p_r_e_p_a_r_e method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_:_:_c_o_m_m_i_t The _D_b_T_x_n_:_:_c_o_m_m_i_t method ends the transaction associated with the DbTxn. If DB_TXN_NOSYNC was not specified, a commit log record is written and flushed to disk, as are all previously written log records. If the transaction is nested, its locks are acquired by the parent transaction, otherwise its locks are released. Any applications that require strict two-phase locking must not release any locks explicitly, leaving them all to be released by _D_b_T_x_n_:_:_c_o_m_m_i_t. The _D_b_T_x_n_:_:_c_o_m_m_i_t method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_:_:_a_b_o_r_t The _D_b_T_x_n_:_:_a_b_o_r_t method causes an abnormal termination of the transaction. The log is played backwards and any nec- essary recovery operations are initiated through the _r_e_c_o_v_e_r method specified to _D_b_T_x_n_M_g_r_:_:_o_p_e_n. After recov- ery is completed, all locks held by the transaction are acquired by the parent transaction in the case of a nested transaction or released in the case of a non-nested trans- action. As is the case for _D_b_T_x_n_:_:_c_o_m_m_i_t, applications that require strict two phase locking should not explic- itly release any locks. The _D_b_T_x_n_:_:_a_b_o_r_t method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_:_:_i_d The _D_b_T_x_n_:_:_i_d method returns the unique transaction id associated with the specified transaction. Locking calls made on behalf of this transaction should use the value returned from _D_b_T_x_n_:_:_i_d as the locker parameter to the _D_b_L_o_c_k_T_a_b_:_:_g_e_t or _D_b_L_o_c_k_T_a_b_:_:_v_e_c calls. TTRRAANNSSAACCTTIIOONNSS Creating transaction protected applications using the Db access methods requires little system customization. In most cases, the default parameters to the locking, log- ging, memory pool, and transaction subsystems will suf- fice. Applications can use _D_b_E_n_v_:_:_a_p_p_i_n_i_t (see _D_b_E_n_v(3)) to perform this initialization, or they may do it explic- itly. Each database operation (i.e., any call to a method under- lying the handles returned by _D_b_:_:_o_p_e_n and _D_b_:_:_c_u_r_s_o_r described in _D_b(3)) is normally performed on behalf of a unique locker. If multiple calls on behalf of the same locker are desired, then transactions must be used. Once the application has initialized the Db subsystems that it is using, it may open the Db access method databases. For applications performing transactions, the databases must be opened after subsystem initialization, and cannot be opened as part of a transaction. Once the databases are opened, the application can group sets of operations into transactions, by surrounding the opera- tions with the appropriate _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n, _D_b_T_x_n_:_:_c_o_m_m_i_t and _D_b_T_x_n_:_:_a_b_o_r_t calls. Databases accessed by a transac- tion must not be closed during the transaction. Note, it is not necessary to transaction protect read-only transac- tions, unless those transactions require repeatable reads. The Db access methods will make the appropriate calls into the lock, log and memory pool subsystems in order to guar- antee that transaction semantics are applied. When the application is ready to exit, all outstanding transactions should have been committed or aborted. At this point, all open Db files should be closed. Once the Db database files are closed, the Db subsystems should be closed, either explicitly or by destroying the _D_b_E_n_v(3) object. It is also possible to use the locking, logging and trans- action subsystems of Db to provide transaction semantics to objects other than those described by the Db access methods. In these cases, the application will need more explicit customization of the subsystems as well as the development of appropriate data-structure-specific recov- ery functions. For example, consider an application that provides trans- action semantics to data stored in plain UNIX files accessed using the _r_e_a_d(2) and _w_r_i_t_e(2) system calls. The operations for which transaction protection is desired are bracketed by calls to _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n and _D_b_T_x_n_:_:_c_o_m_m_i_t. Before data are referenced, the application must make a call to the lock manager, _D_b_L_o_c_k(3), for a lock of the appropriate type (e.g., read) on the object being locked. The object might be a page in the file, a byte, a range of bytes, or some key. It is up to the application to ensure that appropriate locks are acquired. Before a write is performed, the application should acquire a write lock on the object, by making an appropriate call to the lock man- ager, _D_b_L_o_c_k(3)_. Then, the application should make a call to the log manager, _D_b_L_o_g, to record enough information to redo the operation in case of failure after commit and to undo the operation in case of abort. As discussed in the _D_b_L_o_g(3) manual page, the application is responsible for providing any necessary structure to the log record. For example, the application must understand what part of the log record is an operation code, what part identifies the file being modified, what part is redo information, and what part is undo information. After the log message is written, the application may issue the write system call. After all requests are issued, the application may call _D_b_T_x_n_:_:_c_o_m_m_i_t. When _D_b_T_x_n_:_:_c_o_m_m_i_t returns, the caller is guaranteed that all necessary log writes have been written to disk. At any time, the application may call _D_b_T_x_n_:_:_a_b_o_r_t, which will result in the appropriate calls to the _r_e_c_o_v_e_r method to restore the ``database'' to a consistent pre-transac- tion state. (The recover method must be able to either re-apply or undo the update depending on the context, for each different type of log record.) If the application should crash, the recovery process uses the _D_b_L_o_g interface to read the log and call the _r_e_c_o_v_e_r method to restore the database to a consistent state. The _D_b_T_x_n_:_:_p_r_e_p_a_r_e method provides the core functionality to implement distributed transactions, but it does not manage the notification of distributed transaction man- agers. The caller is responsible for issuing _D_b_T_x_n_:_:_p_r_e_- _p_a_r_e calls to all sites participating in the transaction. If all responses are positive, the caller can issue a _D_b_T_x_n_:_:_c_o_m_m_i_t. If any of the responses are negative, the caller should issue a _D_b_T_x_n_:_:_a_b_o_r_t. In general, the _D_b_T_x_n_:_:_p_r_e_p_a_r_e call requires that the transaction log be flushed to disk. TTRRAANNSSAACCTTIIOONN IIDD LLIIMMIITTSS The transaction ID space in Berkeley DB is 2^31, or 2 bil- lion entries. It is possible that some environments may need to be aware of this limitation. Consider an applica- tion performing 600 transactions a second for 15 hours a day. The transaction ID space will run out in roughly 66 days: 2^31 / (600 * 15 * 60 * 60) = 66 Doing only 100 transactions a second exhausts the transac- tion ID space in roughly one year. The transaction ID space is reset each time recovery is run. If you reach the end of your transaction ID space, shut down your applications and restart them after running recovery (see _d_b___r_e_c_o_v_e_r(1) for more information). The most recently allocated transaction ID is the _s_t___l_a_s_t___t_x_n_i_d value in the transaction statistics informa- tion, and is displayed by the _d_b___s_t_a_t(1) utility. EERRRROORRSS Methods marked as returning _e_r_r_n_o will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see _D_b_E_x_c_e_p_t_i_o_n(3). The _D_b_T_x_n_:_:_p_r_e_p_a_r_e method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DbLog::flush(3), fcntl(2), fflush(3), and strerror(3). The _D_b_T_x_n_:_:_c_o_m_m_i_t method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DbLockTab::vec(3), DbLog::put(3), fcntl(2), fflush(3), malloc(3), memcpy(3), and strerror(3). In addition, the _D_b_T_x_n_:_:_c_o_m_m_i_t method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o for the following condi- tions: [EINVAL] The transaction was aborted. The _D_b_T_x_n_:_:_a_b_o_r_t method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DBenv->tx_recover(3), DbLockTab::vec(3), DbLog::get(3), fcntl(2), fflush(3), memset(3), and strerror(3). [EINVAL] The transaction was already aborted. SSEEEE AALLSSOO _L_I_B_T_P_: _P_o_r_t_a_b_l_e_, _M_o_d_u_l_a_r _T_r_a_n_s_a_c_t_i_o_n_s _f_o_r _U_N_I_X, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. BBUUGGSS Nested transactions are not yet implemented. _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___t_h_r_e_a_d(3), _D_b(3), _D_b_c(3), _D_b_E_n_v(3), _D_b_E_x_c_e_p_t_i_o_n(3), _D_b_I_n_f_o(3), _D_b_L_o_c_k(3), _D_b_L_o_c_k_T_a_b(3), _D_b_L_o_g(3), _D_b_L_s_n(3), _D_b_M_p_o_o_l(3), _D_b_M_p_o_o_l_F_i_l_e(3), _D_b_t(3), _D_b_T_x_n(3), _D_b_T_x_n_M_g_r(3)