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
);
Database options including block cache, compression, etc.
txn_db_options
const TransactionDBOptions&
Transaction-specific options including lock timeout, write policy, and deadlock detection.
Path to the database directory.
Output parameter for the opened TransactionDB instance.
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
);
Write options for the transaction.
txn_options
const TransactionOptions&
Transaction-specific options including snapshot settings, lock timeout, and deadlock detection.
Optional transaction handle to reuse instead of allocating a new one.
Returns a pointer to the new transaction. Caller is responsible for deletion.
GetTransactionByName
virtual Transaction* GetTransactionByName(
const TransactionName& name
);
GetAllPreparedTransactions
virtual void GetAllPreparedTransactions(
std::vector<Transaction*>* trans
);
Lock Management
GetLockStatusData
virtual std::unordered_multimap<uint32_t, KeyLockInfo> GetLockStatusData();
GetDeadlockInfoBuffer
virtual std::vector<DeadlockPath> GetDeadlockInfoBuffer();
SetDeadlockInfoBufferSize
virtual void SetDeadlockInfoBufferSize(uint32_t target_size);
Snapshot Management
CreateTimestampedSnapshot
virtual std::pair<Status, std::shared_ptr<const Snapshot>>
CreateTimestampedSnapshot(TxnTimestamp ts);
GetTimestampedSnapshot
virtual std::shared_ptr<const Snapshot> GetTimestampedSnapshot(
TxnTimestamp ts
) const;
ReleaseTimestampedSnapshotsOlderThan
virtual void ReleaseTimestampedSnapshotsOlderThan(TxnTimestamp ts);
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;
};
Maximum number of keys that can be locked per column family. -1 means no limit.
Default wait timeout in milliseconds when a transaction attempts to lock a key.
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;
};
Whether to automatically set a snapshot at transaction start.
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.
See Also