class LMDB::Transaction
The LMDB
environment supports transactional reads and updates. By default, these provide the standard ACID (atomicity, consistency, isolation, durability) behaviors.
Transactions can be committed or aborted. When a transaction is committed, all its effects take effect in the database atomically. When a transaction is aborted, none of its effects take effect.
Transactions span the entire environment. All the updates made in the course of an update transaction – writing records across all databases, creating databases, and destroying databases – are either completed atomically or rolled back.
Transactions can be nested. A child transaction can be started within a parent transaction. The child transaction can commit or abort, at which point the effects of the child become visible to the parent transaction or not. If the parent aborts, all of the changes performed in the context of the parent – including the changes from a committed child transaction – are rolled back.
To create a transaction, call {Environment#transaction} and supply a block for the code to execute in that transaction.
@example Typical usage
env = LMDB.new "databasedir" db1 = env.database "database1" env.transaction do |parent| db2 = env.database "database2", :create => true #=> creates a new database, but it isn't #=> yet committed to storage db1['x'] #=> nil env.transaction do |child1| db2['a'] = 'b' db1['x'] = 'y' end #=> first child transaction commits #=> changes are visible within the parent transaction #=> but are not yet permanent db1['x'] #=> 'y' db2['a'] #=> 'a' env.transaction do |child2| db2['a'] = 'def' db1['x'] = 'ghi' child2.abort #=> second child transaction aborts and rolls #=> back its changes end db1['x'] #=> 'y' db2['a'] #=> 'a' end #=> parent transaction commits and writes database2 #=> and the updates from transaction child1 to #=> storage.
Public Instance Methods
Abort a transaction in process. Any subtransactions of this transaction will be aborted as well.
@note After aborting a transaction, no further database operations
should be done in the block. Any cursors created in the context of the transaction will no longer be valid.
@example Single transaction
env.transaction do |txn| # ... modify the databases ... txn.abort # modifications are rolled back end
@example Child transactions
env.transaction do |txn1| env.transaction.do |txn2| txn1.abort # txn1 and txn2 are both aborted end end
static VALUE transaction_abort(VALUE self) { transaction_finish(self, 0); return Qnil; }
Commit a transaction in process. Any subtransactions of this transaction will be committed as well.
One does not normally need to call commit explicitly; a commit is performed automatically when the block supplied to {Environment#transaction} exits normally.
@note After committing a transaction, no further database operations
should be done in the block. Any cursors created in the context of the transaction will no longer be valid.
@example Single transaction
env.transaction do |txn| # ... modify the databases ... txn.commit end
@example Child transactions
env.transaction do |txn1| env.transaction.do |txn2| txn1.commit # txn1 and txn2 are both committed end end
static VALUE transaction_commit(VALUE self) { transaction_finish(self, 1); return Qnil; }
@overload env
@return [Environment] the environment in which this transaction is running. @example env.transaction do |t| env == t.env # should be true end
static VALUE transaction_env(VALUE self) { TRANSACTION(self, transaction); return transaction->env; }
@overload readonly?
@note This predicate is considered *unstable*; do not get used to it. @return [false,true] whether the transaction is read-only.
static VALUE transaction_is_readonly(VALUE self) { TRANSACTION(self, transaction); //MDB_txn* txn = transaction->txn; return (transaction->flags & MDB_RDONLY) ? Qtrue : Qfalse; }