Artem Krylysov

Pessimistic Transactions #

When using pessimistic transactions, keys involved in write operations are locked to perform conflict detection - the lock manager puts each updated key in a per-DB map, associating it with the transaction ID.

key_locks = {
    "a": T1,
    "b": T1,
    "c": T1,
}

If another transaction tries to update one of the locked keys concurrently, the conflicting transaction T2 blocks until T1 commits or rolls back - if that doesn't happen before the lock timeout, the operation returns an error:

let t2 = db.transaction();
// T1 has not committed yet.
t2.put("c", "2")?; // T2 is blocked waiting until it times out, or until T1 commits.
t2.put("d", "2")?;
// T1 committed.
t2.commit()?;

Locks are released when a transaction commits or rolls back. A third transaction, running at the same time as T1, but modifying a different set of keys, could proceed without being blocked.

By default, the conflict checks are done right when the operation is performed, which doesn't guarantee that no one else has updated the key since the transaction started:

let t1 = db.transaction();
{
    let t2 = db.transaction();
    t2.put("a", "2")?;
    t2.commit()?;
}
t1.put("a", "1")?; // Succeeds since T2 committed before this call.
t1.commit()?;

Setting a snapshot at the beginning of the transaction makes conflict detection catch updates made since the transaction started:

let mut opts = TransactionOptions::default();
// Setting a snapshot is the only difference compared to the previous example.
opts.set_snapshot(true);
let t1 = db.transaction_opt(&WriteOptions::default(), &opts);
{
    let t2 = db.transaction();
    t2.put("a", "2")?;
    t2.commit()?;
}
t1.put("a", "1")?; // Fails because T2 modified key "a" after the snapshot was set for T1.
t1.commit()?;

After T1 acquires a lock on key a, it checks whether the key was updated after the snapshot was set - whether there is a version of the key in the database with a sequence number higher than the snapshot sequence number. If there is, the write returns an error.

Optimistic Transactions #

Optimistic transactions don't check for conflicts on write operations, so put or delete never block or fail. Conflict checking happens on commits.

At a high level, commit-time validation is similar to how it's done in pessimistic transactions, but the implementation is more lightweight. Instead of tracking individual locked keys in a shared map, the lock manager hashes keys into 1M pre-allocated mutexes (yes, 1M is a lot - it trades off memory for reduced contention). Each operation on a key records the published sequence number at the time of the call.

While the mutexes are held for all keys involved in the commit, the transaction checks the memtable. If it contains a key with a sequence number larger than the recorded one, it means another transaction already committed the same key - the commit fails. The mutexes are released after all keys are validated and all updates are applied to the memtable.

Optimistic transactions limit validation to memtables (pessimistic transactions check the whole tree). If the memtable is flushed mid-transaction, there is nothing left to validate against, so the commit fails and the transaction has to be retried.

Mapping to Isolation Levels #

Isolation levels in databases define semantics of concurrent access - what happens when two concurrent transactions access the same data. I'll cover the most common levels used in modern databases. In SQL databases you can set the isolation level explicitly per transaction. There is no similar high-level API in RocksDB, but you can build different levels yourself with lower-level APIs.

Read uncommitted - the lowest isolation level, where the only guarantee is that concurrent transactions won't physically corrupt the database. This permits dirty reads - a transaction seeing uncommitted data from another transaction. Impossible in RocksDB because transaction writes sit in a buffer that gets applied to the database atomically on commit.

Read committed - a transaction sees only committed data, including data committed by other transactions after it started. You get this with a plain db.get, or when transactions don't use snapshots for reads. Two consecutive gets can see different values mid-transaction:

db.put("a", "1")?;
let t1 = db.transaction();
t1.get("a")?; // Returns "1"
{
    let t2 = db.transaction();
    t2.put("a", "2")?;
    t2.commit()?;
}
t1.get("a")?; // Returns "2"

Snapshot isolation - all reads in the transaction see a consistent snapshot of the database, and the transaction succeeds only if no updates it made conflict with updates made by other transactions since the snapshot was created. Can be achieved by enabling snapshots for both reads and write conflict detection - set_snapshot covers only conflict detection, and reads have to go through the transaction's snapshot(). You avoid non-repeatable reads, but the write skew anomaly is possible.

The snippet below illustrates the anomaly that happens when two transactions read the same data, then each updates a different key based on what it read. Alice has two bank accounts, $100 in each. The bank allows a single account to go negative, as long as the total across both accounts stays non-negative. Two concurrent transactions each withdraw $200 from a different account:

db.put("alice.checking", "100")?;
db.put("alice.savings", "100")?;

let mut opts = TransactionOptions::default();
opts.set_snapshot(true);

// T1 withdraws $200 from checking. T2 concurrently runs the same code,
// withdrawing $200 from savings.
let t1 = db.transaction_opt(&WriteOptions::default(), &opts);
let t2 = db.transaction_opt(&WriteOptions::default(), &opts);

let checking = parse_balance(t1.snapshot().get("alice.checking")?); // $100
let savings = parse_balance(t1.snapshot().get("alice.savings")?); // $100
if checking + savings - 200 >= 0 { // $100 + $100 - $200 = $0, the check passes.
    t1.put("alice.checking", (checking - 200).to_string())?; // Set to -$100.
}

// T2 passes the same check against its own snapshot and sets alice.savings to -$100.

// The transactions updated different keys, so conflict validation passes for both.
t1.commit()?;
t2.commit()?;

// Both accounts are now at -$100, the total is -$200.

Serializable - concurrent transactions run as if they were executed in serial order. You can get something close if you use get_for_update with snapshot isolation when transactions involve only point reads - you avoid dirty and non-repeatable reads and write skew. get_for_update is a special version of get used in transactions to avoid read-write conflicts e.g. when updating a key depends on the result of a read. get_for_update triggers conflict checks the same way as put and delete do. Here is the write skew example fixed by reading the balances with get_for_update, the rest of the code stays the same:

// Unlike snapshot reads, get_for_update reads participate in conflict detection.
let checking = parse_balance(t1.get_for_update("alice.checking", true)?); // $100
let savings = parse_balance(t1.get_for_update("alice.savings", true)?); // $100

// With pessimistic transactions, get_for_update blocks until it times out, then
// fails - the key is locked by T1. With optimistic transactions, the call
// succeeds and T2 aborts at commit.
t2.get_for_update("alice.checking", true)?;

The phantom reads anomaly is possible for transactions running range scans:

// Alice has a single account alice.checking.
db.put("alice.checking", "100")?;

let mut opts = TransactionOptions::default();
opts.set_snapshot(true);
let t1 = db.transaction_opt(&WriteOptions::default(), &opts);

// T1 computes the total across Alice's accounts, locking every key the scan returns.
let mut total = 0;
for item in t1.snapshot().iterator(IteratorMode::From(b"alice.", Direction::Forward)) {
    let (key, _) = item?;
    total += parse_balance(t1.get_for_update(key, true)?);
}
// total = $100.

// T2 opens a new account with a $50 deposit.
// The put doesn't conflict with T1 - T1 never read or locked alice.savings.
let t2 = db.transaction();
t2.put("alice.savings", "50")?;
t2.commit()?; // Succeeds.

t1.commit()?; // Succeeds.

T1 commits believing the total is $100, while Alice's accounts now hold $150. The new account is a phantom - get_for_update locked the keys the scan returned, but alice.savings didn't exist yet, so there was nothing to lock.

RocksDB has a range lock manager that locks key ranges instead of individual keys to prevent phantom reads. It was contributed in 2020, but it's not documented anywhere on the RocksDB wiki and not exposed through the C or Java APIs, so the feature is usable only from C++.

Fixing the Transfer #

With all we learned we can finally fix the $10 transfer bug between Alice and Bob. Transactions (either pessimistic or optimistic) with a snapshot set, using get_for_update instead of plain get, are what we need - another transaction can't change a balance between the read and the write without triggering a conflict:

let mut opts = TransactionOptions::default();
opts.set_snapshot(true);
let tx = db.transaction_opt(&WriteOptions::default(), &opts);

let Ok(alice_balance) = tx.get_for_update("alice.balance", true) else {
    // Can happen with pessimistic transactions.
    return Err("another transaction updated Alice's balance".into());
};
let alice_balance = parse_balance(alice_balance);
if alice_balance < 10 {
    return Err("not enough money".into());
}

let Ok(bob_balance) = tx.get_for_update("bob.balance", true) else {
    // Can happen with pessimistic transactions.
    return Err("another transaction updated Bob's balance".into());
};
let bob_balance = parse_balance(bob_balance);

tx.put("alice.balance", (alice_balance - 10).to_string())?;
tx.put("bob.balance", (bob_balance + 10).to_string())?;

if tx.commit().is_err() {
    // Can happen with optimistic transactions.
    return Err("another transaction updated Bob's or Alice's balance or the memtable was flushed".into());
}

Optimistic vs Pessimistic Performance #

From the user perspective, the only difference between pessimistic and optimistic transactions is where a transaction can abort on a conflict. Pessimistic transactions acquire locks on every write operation and abort early on conflicts (after exceeding the lock timeout). Optimistic transactions require no per-key locks on writes - coarse-grained locks are taken for the duration of a commit. Optimistic transactions typically provide higher throughput on workloads where conflicts between transactions are rare and where retrying the entire transaction on a conflict is cheap.

I benchmarked two workloads (source code is here) - one where pessimistic transactions win and one where optimistic transactions win.

In the "mostly read" workload, every transaction reads a shared key with get_for_update and writes a unique key - roughly one transaction in 1024 replaces the shared key instead. Starting from 2 threads, the throughput of optimistic transactions stays flat, while pessimistic transactions queue on the shared key's lock:

In the "contended key" workload, every transaction reads the same key with get_for_update, does CPU-bound work and writes the key back. Pessimistic transactions wait on the lock without consuming CPU, so the work runs once per commit. Optimistic transactions discover the conflict only at commit, after the work is done, redoing the expensive work on retry:

Who Uses RocksDB-native Transactions #

MyRocks - the MySQL storage engine built on RocksDB, and ArangoDB are the only large projects I'm aware of that rely on RocksDB transactions. Facebook's MyRocks repository was archived on GitHub on Mar 1, 2026, but the engine is still available as a part of MariaDB or Percona Server.

TiDB/TiKV and YugabyteDB, which run on RocksDB, don't use RocksDB-native transactions. CockroachDB's RocksDB-inspired key-value store Pebble doesn't support transactions at all. TiDB, YugabyteDB and CockroachDB implement their own distributed transactional layer above the key-value stores. The reason for this is that RocksDB-native transactions are node-local, i.e. the locks are held per key-value store instance running on a single node, and with a distributed database you have to coordinate transactions across multiple nodes.