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() click to toggle source

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() click to toggle source

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;
}
env() click to toggle source

@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;
}
readonly?() click to toggle source

@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;
}