TransactionDB

TransactionDB provides transaction support with ACID guarantees for RocksDB. It extends the base DB interface with transactional capabilities including snapshot isolation, conflict detection, and two-phase commit.

Opening a TransactionDB

Open

static Status Open(
  const Options& options,
  const TransactionDBOptions& txn_db_options,
  const std::string& dbname,
  TransactionDB** dbptr
);

static Status Open(
  const DBOptions& db_options,
  const TransactionDBOptions& txn_db_options,
  const std::string& dbname,
  const std::vector<ColumnFamilyDescriptor>& column_families,
  std::vector<ColumnFamilyHandle*>* handles,
  TransactionDB** dbptr
);

Opens a TransactionDB similar to DB::Open().

const Options&

Database options including block cache, compression, etc.

const TransactionDBOptions&

Transaction-specific options including lock timeout, write policy, and deadlock detection.

const std::string&

Path to the database directory.

TransactionDB**

Output parameter for the opened TransactionDB instance.

Status

Returns OK on success, or an error status if the database cannot be opened.

Transaction Management

BeginTransaction

virtual Transaction* BeginTransaction(
  const WriteOptions& write_options,
  const TransactionOptions& txn_options = TransactionOptions(),
  Transaction* old_txn = nullptr
);

Starts a new transaction.

const WriteOptions&

Write options for the transaction.

const TransactionOptions&

Transaction-specific options including snapshot settings, lock timeout, and deadlock detection.

Transaction*

Optional transaction handle to reuse instead of allocating a new one.

Transaction*

Returns a pointer to the new transaction. Caller is responsible for deletion.

GetTransactionByName

virtual Transaction* GetTransactionByName(
  const TransactionName& name
);

Retrieves a transaction by its name.

GetAllPreparedTransactions

virtual void GetAllPreparedTransactions(
  std::vector<Transaction*>* trans
);

Retrieves all prepared transactions (for two-phase commit).

Lock Management

GetLockStatusData

virtual std::unordered_multimap<uint32_t, KeyLockInfo> GetLockStatusData();

Returns the set of all locks held, mapped by column family ID.

GetDeadlockInfoBuffer

virtual std::vector<DeadlockPath> GetDeadlockInfoBuffer();

Retrieves information about detected deadlocks.

SetDeadlockInfoBufferSize

virtual void SetDeadlockInfoBufferSize(uint32_t target_size);

Sets the number of latest deadlocks to track.

Snapshot Management

CreateTimestampedSnapshot

virtual std::pair<Status, std::shared_ptr<const Snapshot>>
CreateTimestampedSnapshot(TxnTimestamp ts);

Creates a snapshot and assigns a timestamp to it.

GetTimestampedSnapshot

virtual std::shared_ptr<const Snapshot> GetTimestampedSnapshot(
  TxnTimestamp ts
) const;

Retrieves the snapshot corresponding to the given timestamp.

ReleaseTimestampedSnapshotsOlderThan

virtual void ReleaseTimestampedSnapshotsOlderThan(TxnTimestamp ts);

Releases timestamped snapshots older than or equal to the specified timestamp.

Options and Configuration

TransactionDBOptions

struct TransactionDBOptions {
  int64_t max_num_locks = -1;
  uint32_t max_num_deadlocks = 5;
  size_t num_stripes = 16;
  int64_t transaction_lock_timeout = 1000;
  int64_t default_lock_timeout = 1000;
  std::shared_ptr<TransactionDBMutexFactory> custom_mutex_factory;
  TxnDBWritePolicy write_policy = WRITE_COMMITTED;
  std::shared_ptr<LockManagerHandle> lock_mgr_handle;
};

int64_t

Maximum number of keys that can be locked per column family. -1 means no limit.

int64_t

Default wait timeout in milliseconds when a transaction attempts to lock a key.

TxnDBWritePolicy

When to write data: WRITE_COMMITTED (default), WRITE_PREPARED, or WRITE_UNPREPARED.

TransactionOptions

struct TransactionOptions {
  bool set_snapshot = false;
  bool deadlock_detect = false;
  int64_t lock_timeout = -1;
  int64_t expiration = -1;
  int64_t deadlock_detect_depth = 50;
  size_t max_write_batch_size = 0;
};

bool

Whether to automatically set a snapshot at transaction start.

bool

Whether to check for deadlocks before acquiring locks.

Example

#include "rocksdb/utilities/transaction_db.h"

using namespace ROCKSDB_NAMESPACE;

// Open TransactionDB
Options options;
TransactionDBOptions txn_db_options;
options.create_if_missing = true;
TransactionDB* txn_db;

Status s = TransactionDB::Open(options, txn_db_options, "/tmp/testdb", &txn_db);
assert(s.ok());

// Start a transaction
WriteOptions write_options;
TransactionOptions txn_options;
Transaction* txn = txn_db->BeginTransaction(write_options, txn_options);

// Write within transaction
s = txn->Put("key1", "value1");
assert(s.ok());

// Read within transaction
std::string value;
s = txn->Get(ReadOptions(), "key1", &value);
assert(s.ok());

// Commit transaction
s = txn->Commit();
assert(s.ok());

delete txn;
delete txn_db;

Write Policies

WRITE_COMMITTED

Default policy. Data is written at commit time, providing the strongest consistency guarantees.

WRITE_PREPARED

Experimental. Data is written during the prepare phase of two-phase commit.

WRITE_UNPREPARED

Experimental. Data is written before the prepare phase to support large transactions.

Database

Read & Write

Transactions

Storage

Utilities

Opening a TransactionDB

Open

Transaction Management

BeginTransaction

GetTransactionByName

GetAllPreparedTransactions

Lock Management

GetLockStatusData

GetDeadlockInfoBuffer

SetDeadlockInfoBufferSize

Snapshot Management

CreateTimestampedSnapshot

GetTimestampedSnapshot

ReleaseTimestampedSnapshotsOlderThan

Options and Configuration

TransactionDBOptions

TransactionOptions

Example

Write Policies

WRITE_COMMITTED

WRITE_PREPARED

WRITE_UNPREPARED

See Also

​Opening a TransactionDB

​Open

​Transaction Management

​BeginTransaction

​GetTransactionByName

​GetAllPreparedTransactions

​Lock Management

​GetLockStatusData

​GetDeadlockInfoBuffer

​SetDeadlockInfoBufferSize

​Snapshot Management

​CreateTimestampedSnapshot

​GetTimestampedSnapshot

​ReleaseTimestampedSnapshotsOlderThan

​Options and Configuration

​TransactionDBOptions

​TransactionOptions

​Example

​Write Policies

​WRITE_COMMITTED

​WRITE_PREPARED

​WRITE_UNPREPARED

​See Also

Opening a TransactionDB

Open

Transaction Management

BeginTransaction

GetTransactionByName

GetAllPreparedTransactions

Lock Management

GetLockStatusData

GetDeadlockInfoBuffer

SetDeadlockInfoBufferSize

Snapshot Management

CreateTimestampedSnapshot

GetTimestampedSnapshot

ReleaseTimestampedSnapshotsOlderThan

Options and Configuration

TransactionDBOptions

TransactionOptions

Example

Write Policies

WRITE_COMMITTED

WRITE_PREPARED

WRITE_UNPREPARED

See Also