Struct Transaction 

pub struct Transaction<'db, DB> { /* private fields */ }

RocksDB Transaction.

To use transactions, you must first create a TransactionDB or OptimisticTransactionDB.

A Transaction must not outlive the TransactionDB it was created from:

use rust_rocksdb::{SingleThreaded, TransactionDB};

let _txn = {
    let db = TransactionDB::<SingleThreaded>::open_default("foo").unwrap();
    db.transaction()
};

A Snapshot taken from a Transaction must not outlive the Transaction:

use rust_rocksdb::{SingleThreaded, TransactionDB};

let db = TransactionDB::<SingleThreaded>::open_default("foo").unwrap();
let _snapshot = {
    let txn = db.transaction();
    txn.snapshot()
};

Implementations

impl<DB> Transaction<'_, DB>

pub fn commit(self) -> Result<(), Error>

Write all batched keys to the DB atomically.

May return any error that could be returned by DB::write.

If this transaction was created by a TransactionDB, an error of the Expired kind may be returned if this transaction has lived longer than expiration time in TransactionOptions.

If this transaction was created by an OptimisticTransactionDB, an error of the Busy kind may be returned if the transaction could not guarantee that there are no write conflicts. An error of the TryAgain kind may be returned if the memtable history size is not large enough (see Options::set_max_write_buffer_size_to_maintain).

pub fn set_name(&self, name: &[u8]) -> Result<(), Error>

pub fn get_name(&self) -> Option<Vec<u8>>

pub fn prepare(&self) -> Result<(), Error>

pub fn snapshot(&self) -> SnapshotWithThreadMode<'_, Self>

Returns snapshot associated with transaction if snapshot was enabled in TransactionOptions. Otherwise, returns a snapshot with nullptr inside which doesn’t affect read operations.

pub fn rollback(&self) -> Result<(), Error>

Discard all batched writes in this transaction.

pub fn set_savepoint(&self)

Record the state of the transaction for future calls to rollback_to_savepoint. May be called multiple times to set multiple save points.

pub fn rollback_to_savepoint(&self) -> Result<(), Error>

Undo all operations in this transaction since the most recent call to set_savepoint and removes the most recent set_savepoint.

Returns error if there is no previous call to set_savepoint.

pub fn get<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<Vec<u8>>, Error>

Get the bytes associated with a key value.

See get_cf_opt for details.

pub fn get_pinned<K: AsRef<[u8]>>( &self, key: K, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_cf<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<Option<Vec<u8>>, Error>

Get the bytes associated with a key value and the given column family.

See get_cf_opt for details.

pub fn get_pinned_cf<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_for_update<K: AsRef<[u8]>>( &self, key: K, exclusive: bool, ) -> Result<Option<Vec<u8>>, Error>

Get the key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction).

See get_for_update_cf_opt for details.

pub fn get_pinned_for_update<K: AsRef<[u8]>>( &self, key: K, exclusive: bool, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_for_update_cf<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, exclusive: bool, ) -> Result<Option<Vec<u8>>, Error>

Get the key in the given column family and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction).

See get_for_update_cf_opt for details.

pub fn get_pinned_for_update_cf<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, exclusive: bool, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_opt<K: AsRef<[u8]>>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

Returns the bytes associated with a key value with read options.

See get_cf_opt for details.

pub fn get_pinned_opt<K: AsRef<[u8]>>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

Get the bytes associated with a key value and the given column family with read options.

This function will also read pending changes in this transaction. Currently, this function will return an error of the MergeInProgress kind if the most recent write to the queried key in this batch is a Merge.

pub fn get_pinned_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_for_update_opt<K: AsRef<[u8]>>( &self, key: K, exclusive: bool, opts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

Get the key with read options and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction).

See get_for_update_cf_opt for details.

pub fn get_pinned_for_update_opt<K: AsRef<[u8]>>( &self, key: K, exclusive: bool, opts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn get_for_update_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, exclusive: bool, opts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

Get the key in the given column family with read options and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction).

Currently, this function will return an error of the MergeInProgress if the most recent write to the queried key in this batch is a Merge.

If this transaction was created by a TransactionDB, it can return error of kind:

• Busy if there is a write conflict.
• TimedOut if a lock could not be acquired.
• TryAgain if the memtable history size is not large enough.
• MergeInProgress if merge operations cannot be resolved.
• or other errors if this key could not be read.

If this transaction was created by an [OptimisticTransactionDB], get_for_update_opt can cause commit to fail. Otherwise, it could return any error that could be returned by [DB::get].

pub fn get_pinned_for_update_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, exclusive: bool, opts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

pub fn multi_get<K, I>(&self, keys: I) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys.

pub fn multi_get_opt<K, I>( &self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys using read options.

pub fn multi_get_cf<'a, 'b: 'a, K, I, W>( &'a self, keys: I, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families.

pub fn multi_get_cf_opt<'a, 'b: 'a, K, I, W>( &'a self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families using read options.

pub fn multi_get_for_update<K, I>( &self, keys: I, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys, marking every key read for update.

See multi_get_for_update_cf_opt for details.

pub fn multi_get_for_update_opt<K, I>( &self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

Return the values associated with the given keys using read options, marking every key read for update.

See multi_get_for_update_cf_opt for details.

pub fn multi_get_for_update_cf<'a, 'b: 'a, K, I, W>( &'a self, keys: I, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families, marking every key read for update.

See multi_get_for_update_cf_opt for details.

pub fn multi_get_for_update_cf_opt<'a, 'b: 'a, K, I, W>( &'a self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: 'b + AsColumnFamilyRef,

Return the values associated with the given keys and column families using read options, marking every key read for update.

This is get_for_update_cf_opt over a batch of keys: each key is fetched and conflict checked, so the transaction only commits if none of them were written outside it after the read (or after the snapshot, if one is set). There is no exclusive parameter because RocksDB always takes the lock exclusively here.

Locking is all or nothing. RocksDB locks every key before reading any of them, and if one lock fails it returns that same error for every entry without performing the reads. Once the locks are held, each key is read on its own, so after that point the results can differ per key.

pub fn put<K: AsRef<[u8]>, V: AsRef<[u8]>>( &self, key: K, value: V, ) -> Result<(), Error>

Put the key value in default column family and do conflict checking on the key.

See put_cf for details.

pub fn put_cf<K: AsRef<[u8]>, V: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, ) -> Result<(), Error>

Put the key value in the given column family and do conflict checking on the key.

If this transaction was created by a TransactionDB, it can return error of kind:

• Busy if there is a write conflict.
• TimedOut if a lock could not be acquired.
• TryAgain if the memtable history size is not large enough.
• MergeInProgress if merge operations cannot be resolved.
• or other errors on unexpected failures.

pub fn merge<K: AsRef<[u8]>, V: AsRef<[u8]>>( &self, key: K, value: V, ) -> Result<(), Error>

Merge value with existing value of key, and also do conflict checking on the key.

See merge_cf for details.

pub fn merge_cf<K: AsRef<[u8]>, V: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, value: V, ) -> Result<(), Error>

Merge value with existing value of key in the given column family, and also do conflict checking on the key.

If this transaction was created by a TransactionDB, it can return error of kind:

• Busy if there is a write conflict.
• TimedOut if a lock could not be acquired.
• TryAgain if the memtable history size is not large enough.
• MergeInProgress if merge operations cannot be resolved.
• or other errors on unexpected failures.

pub fn delete<K: AsRef<[u8]>>(&self, key: K) -> Result<(), Error>

Delete the key value if it exists and do conflict checking on the key.

See delete_cf for details.

pub fn delete_cf<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, ) -> Result<(), Error>

Delete the key value in the given column family and do conflict checking.

If this transaction was created by a TransactionDB, it can return error of kind:

• Busy if there is a write conflict.
• TimedOut if a lock could not be acquired.
• TryAgain if the memtable history size is not large enough.
• MergeInProgress if merge operations cannot be resolved.
• or other errors on unexpected failures.

pub fn iterator<'a: 'b, 'b>( &'a self, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, Self>

pub fn iterator_opt<'a: 'b, 'b>( &'a self, mode: IteratorMode<'_>, readopts: ReadOptions, ) -> DBIteratorWithThreadMode<'b, Self>

pub fn iterator_cf_opt<'a: 'b, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, readopts: ReadOptions, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, Self>

Opens an iterator using the provided ReadOptions. This is used when you want to iterate over a specific ColumnFamily with a modified ReadOptions.

pub fn full_iterator<'a: 'b, 'b>( &'a self, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, Self>

Opens an iterator with set_total_order_seek enabled. This must be used to iterate across prefixes when set_memtable_factory has been called with a Hash-based implementation.

pub fn prefix_iterator<'a: 'b, 'b, P: AsRef<[u8]>>( &'a self, prefix: P, ) -> DBIteratorWithThreadMode<'b, Self>

pub fn iterator_cf<'a: 'b, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, Self>

pub fn full_iterator_cf<'a: 'b, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, mode: IteratorMode<'_>, ) -> DBIteratorWithThreadMode<'b, Self>

pub fn prefix_iterator_cf<'a, P: AsRef<[u8]>>( &'a self, cf_handle: &impl AsColumnFamilyRef, prefix: P, ) -> DBIteratorWithThreadMode<'a, Self>

pub fn raw_iterator<'a: 'b, 'b>( &'a self, ) -> DBRawIteratorWithThreadMode<'b, Self>

Opens a raw iterator over the database, using the default read options

pub fn raw_iterator_cf<'a: 'b, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, ) -> DBRawIteratorWithThreadMode<'b, Self>

Opens a raw iterator over the given column family, using the default read options

pub fn raw_iterator_opt<'a: 'b, 'b>( &'a self, readopts: ReadOptions, ) -> DBRawIteratorWithThreadMode<'b, Self>

Opens a raw iterator over the database, using the given read options

pub fn raw_iterator_cf_opt<'a: 'b, 'b>( &'a self, cf_handle: &impl AsColumnFamilyRef, readopts: ReadOptions, ) -> DBRawIteratorWithThreadMode<'b, Self>

Opens a raw iterator over the given column family, using the given read options

pub fn get_writebatch(&self) -> WriteBatchWithTransaction<true>

pub fn rebuild_from_writebatch( &self, writebatch: &WriteBatchWithTransaction<true>, ) -> Result<(), Error>

pub fn rebuild_from_writebatch_wi( &self, writebatch: &WriteBatchWithIndex, ) -> Result<(), Error>

Replays the writes indexed by writebatch into this transaction.

RocksDB walks the batch underlying the index and re-applies each record through this transaction’s own put, merge and delete, so the keys end up tracked and conflict checked as if they had been written on the transaction directly. Under TxnDBWritePolicy::WriteUnprepared the records are already in the DB from WAL replay, so RocksDB only re-tracks the keys instead of rewriting them.

Nothing is cleared first, so this layers on top of whatever the transaction already holds. Run it on a fresh transaction that has not been prepared or committed, the way RocksDB uses it when rebuilding prepared transactions during recovery. writebatch is only read, never taken over or modified.

Returns an error if the batch carries two-phase commit markers, or if a replayed write fails for any of the reasons listed on put_cf.

pub fn put_log_data<V: AsRef<[u8]>>(&self, log_data: V)

Appends a blob of arbitrary size to the records in this transaction.

The blob goes into the WAL only. It is never written to an SST file and is never visible to any read, so no get or iterator will ever return it. Iterating the transaction’s write batch surfaces it through WriteBatchIterator::log_data, interleaved with the puts, deletes and merges in insertion order. It consumes no sequence number and does not change the batch’s count.

A typical use is stamping the transaction log with data needed for replication.

pub fn set_commit_timestamp(&self, val: u64)

Sets the commit timestamp for this transaction.

Only meaningful when the column family uses user-defined timestamps. RocksDB reports an unsupported timestamp through a status that the C API discards, so calling this on a transaction without timestamp support does nothing.

pub fn set_read_timestamp_for_validation(&self, val: u64)

Sets the read timestamp used to validate this transaction’s reads.

Only meaningful when the column family uses user-defined timestamps. RocksDB reports an unsupported timestamp through a status that the C API discards, so calling this on a transaction without timestamp support does nothing.

Trait Implementations

impl<DB> DBAccess for Transaction<'_, DB>

unsafe fn create_snapshot(&self) -> *const rocksdb_snapshot_t

unsafe fn release_snapshot(&self, snapshot: *const rocksdb_snapshot_t)

unsafe fn create_iterator( &self, readopts: &ReadOptions, ) -> *mut rocksdb_iterator_t

unsafe fn create_iterator_cf( &self, cf_handle: *mut rocksdb_column_family_handle_t, readopts: &ReadOptions, ) -> *mut rocksdb_iterator_t

fn get_opt<K: AsRef<[u8]>>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

fn get_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<Vec<u8>>, Error>

fn get_pinned_opt<K: AsRef<[u8]>>( &self, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

fn get_pinned_cf_opt<K: AsRef<[u8]>>( &self, cf: &impl AsColumnFamilyRef, key: K, readopts: &ReadOptions, ) -> Result<Option<DBPinnableSlice<'_>>, Error>

fn multi_get_opt<K, I>( &self, keys: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = K>,

fn multi_get_cf_opt<'b, K, I, W>( &self, keys_cf: I, readopts: &ReadOptions, ) -> Vec<Result<Option<Vec<u8>>, Error>>

where K: AsRef<[u8]>, I: IntoIterator<Item = (&'b W, K)>, W: AsColumnFamilyRef + 'b,

impl<DB> Drop for Transaction<'_, DB>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<DB> Send for Transaction<'_, DB>