Skip to content
JZLeetCode
Go back

System Design - How TiDB Isolates a Failed Statement Inside a Transaction

Table of contents

Open Table of contents

One transaction, two different kinds of rollback

Assume the orders table uses id as its primary key. Consider a client that runs three statements in one transaction:

BEGIN;
INSERT INTO orders VALUES (101, 'ready');
INSERT INTO orders VALUES (101, 'conflict');
COMMIT;

Suppose the second statement fails. The client expects the first statement to remain part of the transaction, while the failed statement contributes no partial writes. It can then decide whether to fix the problem, run another statement, or roll back the whole transaction.

That requires two rollback boundaries:

TiDB handles the statement boundary in its SQL session layer. The important pieces are the session methods StmtCommit and StmtRollback, the LazyTxn wrapper, and the transaction’s in-memory MemBuffer. The walkthrough below follows those pieces in TiDB’s session transaction source.

Where a statement’s writes go

An executor does not normally send each row change straight to TiKV as soon as it evaluates the SQL. TiDB first records mutations in the transaction’s in-memory buffer. LazyTxn wraps the lower-level kv.Transaction and creates a staging area in that buffer for the current statement.

SQL executor
     |
     | statement succeeded or failed
     v
session.StmtCommit / session.StmtRollback
     |
     v
LazyTxn
     |
     v
transaction MemBuffer
     |
     | final transaction COMMIT
     v
TiDB transaction client --> TiKV

Think of the MemBuffer as a list of pending changes owned by the transaction. A statement stage is a temporary layer on top of that list. It lets TiDB either publish the layer into the transaction’s buffer or throw it away.

The MemBuffer interface in pkg/kv/kv.go describes the three operations that matter:

These are buffer operations. Releasing a stage does not by itself commit the SQL transaction or make its rows visible to other transactions.

The successful statement path

When a transaction becomes active, LazyTxn.initStmtBuf records the current buffer length and opens a stage. The stage begins before the statement writes are added.

After the executor finishes the statement successfully, session.StmtCommit asks the transaction manager to finish its statement work and calls LazyTxn.flushStmtBuf. That method releases the stage, moving the statement’s changes into the parent transaction buffer. TiDB then cleans up the stage bookkeeping and opens a fresh stage for the next statement.

Before statement 1:
  transaction buffer: [ ]
  active stage:       [ ]

Statement 1 succeeds:
  Release(stage 1)
  transaction buffer: [ statement 1 writes ]
  active stage:       [ ]

The earlier writes are now part of the transaction, but the transaction is still open. A later ROLLBACK can still discard them.

The failed statement path

If the executor reports a statement error, TiDB can call session.StmtRollback. That method notifies the transaction manager and calls LazyTxn.cleanup. The cleanup removes the current stage, which discards writes that the failed statement had placed there. It then opens a new stage so the session can continue with another statement.

Before statement 2:
  transaction buffer: [ statement 1 writes ]
  active stage:       [ ]

Statement 2 fails:
  active stage:       [ partial statement 2 writes ]
  Cleanup(stage 2)

After statement rollback:
  transaction buffer: [ statement 1 writes ]
  active stage:       [ ]

This is why a failed statement does not have to erase successful statements that came before it. The outer transaction still owns statement 1’s writes; only the un-released stage for statement 2 is discarded.

The sequence can be summarized as:

start stage
    |
    +-- statement succeeds --> Release into transaction buffer
    |
    +-- statement fails -----> Cleanup and discard this stage

The implementation is in LazyTxn.initStmtBuf, flushStmtBuf, and cleanupStmtBuf. The session callbacks that choose the success or failure path are StmtCommit and StmtRollback.

Statement commit is not transaction commit

The similar names can be confusing. session.StmtCommit means “this SQL statement succeeded; merge its changes into the transaction.” It does not mean “finish the transaction.”

The client issues COMMIT separately. TiDB then commits the underlying transaction. At the storage layer, TiKV’s Prewrite command handles the first phase of two-phase commit. That later protocol decides whether the transaction’s accumulated writes become committed data. Statement staging happens earlier and only decides which writes are allowed to remain in the transaction’s buffer.

This distinction also explains why the layer matters for both optimistic and pessimistic transactions: the mode changes conflict handling and locking behavior, while statement staging protects the transaction’s pending writes from a failed statement.

There are paths with additional rules. LazyTxn does not create a statement stage for a pipelined transaction. Also, some errors invalidate or abort the transaction itself; statement staging does not override those transaction-level rules. This article follows the ordinary statement success or failure path.

Settings that shape the example

These settings define the outer transaction context. The statement stage is an internal mechanism that protects the transaction’s pending mutations inside that context.

References

  1. TiDB source, LazyTxn and statement callbacks
  2. TiDB source, MemBuffer staging interface
  3. TiDB documentation, Transactions
  4. TiDB documentation, autocommit and tidb_txn_mode
  5. TiKV source, Prewrite command
Share this post on:

Previous Post
System Design - How Kubernetes Operators Reconcile Applications
Next Post
LeetCode 1358 Number of Substrings Containing All Three Characters