Vitess Two-Phase Commit: Concepts, Implementation, and Exception Handling

Before diving into Vitess, the article reviews the four ACID properties—Atomicity, Consistency, Isolation, and Durability—using a bank withdrawal example to illustrate each concept.

It then describes how large‑scale internet services split data across multiple MySQL shards, using user ID modulo 64 to route data, and introduces a typical order‑creation workflow that requires both credit deduction and order generation to be atomic.

The core of the discussion focuses on Vitess’s architecture: vtgate acts as the transaction manager (coordinator), while each vttablet together with its MySQL instance forms a shard (resource manager). The article explains how vtgate routes requests, maintains per‑session transaction IDs, and uses an activePool for normal transactions.

For distributed transactions, Vitess implements a two‑phase commit (2PC). The article enumerates the six phases:

Generate a global transaction ID (e.g., Shard1:TX1 ) and record metadata on the first shard (mmShard).

Record metadata (state, start time, participants) in the mmShard database using a separate connection.

Prepare phase: each participant moves its local transaction connection to a preparedPool keyed by the global ID and writes a redo log.

StartCommit phase: the coordinator updates the global state to Committed on mmShard.

CommitPrepare phase: participants retrieve their connections from preparedPool , delete the redo log, and commit.

ConcludeTransaction phase: the coordinator deletes the metadata entry from mmShard.

Code excerpts illustrate the 2PC implementation in Vitess (Go language). For example, the commit function begins with:

func (txc *TxConn) commit2PC(ctx context.Context, session *SafeSession) error {

and proceeds through participant collection, transaction creation, preparation, start‑commit, commit‑prepared, and conclusion, handling errors at each step.

The article also details exception handling for each phase, showing how Vitess rolls back or resolves transactions when failures occur, including network issues, shard crashes, or coordinator crashes. It explains the role of a watchdog in each vttablet that monitors transaction timeouts and triggers ResolveTransaction calls to the coordinator.

Finally, a FAQ section addresses common questions about the necessity of a separate preparedPool , concurrency of resolve calls, interpretation of commit errors, compliance with ACID, alternative transaction models, performance impact (typically <5 ms overhead), and real‑world applicability.