Class BDB::Txn
In: bdb.rb
Parent: Object

The transaction subsystem makes operations atomic, consistent, isolated, and durable in the face of system and application failures. The subsystem requires that the data be properly logged and locked in order to attain these properties. Berkeley DB contains all the components necessary to transaction-protect the Berkeley DB access methods and other forms of data may be protected if they are logged and locked appropriately.

The transaction subsystem is created, initialized, and opened by calls to BDB::Env#open with the BDB::INIT_TXN flag (or BDB::INIT_TRANSACTION) specified. Note that enabling transactions automatically enables logging, but does not enable locking, as a single thread of control that needed atomicity and recoverability would not require it.

The transaction is created with BDB::Env#begin or with begin

Methods
abort    assoc    associate    begin    close    commit    dbremove    dbrename    discard    id    open_db    prepare    txn_abort    txn_assoc    txn_begin    txn_close    txn_commit    txn_discard    txn_id    txn_prepare    txn_prepare   
Public Instance methods
abort()

Abort the transaction. This is will terminate the transaction.

txn_abort()

same than abort

assoc(db, ...)

Associate a database with the transaction, return a new database handle which is transaction protected.

associate(db, ...)

same than assoc

txn_assoc(db, ...)

same than assoc

begin(flags = 0, db, ...) {|txn, db, ... end| ...}

begin a transaction (the transaction manager must be enabled). flags can have the value DBD::TXN_COMMIT, in this case the transaction will be commited at end.

Return a new transaction object, and the associated database handle if specified.

If begin is called as an iterator, commit and abort will terminate the iterator.

env.begin(db) do |txn, b| … end

is the same than

env.begin do |txn| b = txn.assoc(db) … end

An optional hash can be given with the possible keys "flags", "set_timeout", "set_txn_timeout", "set_lock_timeout"

txn_begin(flags = 0, db, ...)
commit(flags = 0)

Commit the transaction. This will finish the transaction. The flags can have the value

BDB::TXN_SYNC Synchronously flush the log. This means the transaction will exhibit all of the ACID (atomicity, consistency and isolation and durability) properties. This is the default value.

BDB::TXN_NOSYNC Do not synchronously flush the log. This means the transaction will exhibit the ACI (atomicity, consistency and isolation) properties, but not D (durability), i.e., database integrity will be maintained but it is possible that this transaction may be undone during recovery instead of being redone.

This behavior may be set for an entire Berkeley DB environment as part of the open interface.

close(flags = 0)

same than commit

txn_commit(flags = 0)

same than commit

txn_close(flags = 0)

same than commit

discard()

only with BDB::VERSION_MAJOR == 3 && BDB::VERSION_MINOR >= 3

Discard a prepared but not resolved transaction handle, must be called only within BDB::Env#recover

txn_discard()

same than discard

dbremove(file, database = nil, flags = 0)

only with BDB::VERSION_MAJOR == 4 && BDB::VERSION_MINOR >= 1

remove the database specified by file and database. If no database is nil, the underlying file represented by file is removed, incidentally removing all databases that it contained.

The flags value must be set to 0 or BDB::AUTO_COMMIT

dbrename(file, database, newname, flags = 0)

only with BDB::VERSION_MAJOR == 4 && BDB::VERSION_MINOR >= 1

rename the database specified by file and database to newname. If database is nil, the underlying file represented by file is renamed, incidentally renaming all databases that it contained.

The flags value must be set to 0 or BDB::AUTO_COMMIT

id()

The txn_id function returns the unique transaction id associated with the specified transaction. Locking calls made on behalf of this transaction should use the value returned from txn_id as the locker parameter to the lock_get or lock_vec calls.

txn_id()

same than id

open_db(type, name = nil, subname = nil, flags = 0, mode = 0)

Only with DB >= 4.1

open the database in the current transaction. type must be one of the constant BDB::BTREE, BDB::HASH, BDB::RECNO, BDB::QUEUE. See open for other arguments

prepare()

The txn_prepare function initiates the beginning of a two-phase commit.

In a distributed transaction environment, Berkeley DB can be used as a local transaction manager. In this case, the distributed transaction manager must send prepare messages to each local manager. The local manager must then issue a txn_prepare 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 prepare messages should it issue any commit messages.

txn_prepare()

same than prepare

txn_prepare(id)

same than prepare