Skip to content

convert 2PC in TiDB sequence diagram from PNG to Mermaid code (#22560) #22561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ti-chi-bot merged 2 commits into from
Mar 13, 2026
Merged

convert 2PC in TiDB sequence diagram from PNG to Mermaid code (#22560) #22561

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c1ab390
convert 2PC in TiDB sequence diagram from PNG to Mermaid code
Oreoxmt Mar 13, 2026
09a6ad9
fix
Oreoxmt Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion optimistic-transaction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,56 @@ Before enabling optimistic transactions, make sure that your application correct

To support distributed transactions, TiDB adopts two-phase commit (2PC) in optimistic transactions. The procedure is as follows:

![2PC in TiDB](/media/2pc-in-tidb.png)
```mermaid
---
title: 2PC in TiDB
---
sequenceDiagram
participant client
participant TiDB
participant PD
participant TiKV

client->>TiDB: begin
TiDB->>PD: get ts as start_ts

loop excute SQL
alt do read
TiDB->>PD: get region from PD or cache
TiDB->>TiKV: get data from TiKV or cache with start_ts
TiDB-->>client: return read result
end
alt do write
TiDB-->>TiDB: write in cache
TiDB-->>client: return write result
end
end

client->>TiDB: commit

opt start 2PC
TiDB-->>TiDB: for all keys need to write,choose first one as primary
TiDB->>PD: locate each key
TiDB-->>TiDB: group keys by region to [](region,keys)

opt prewrite with start_ts
TiDB->>TiKV: prewrite(primary_key,start_ts)
loop prewrite to each region in [](region,keys) parallelly
TiDB->>TiKV: prewrite(keys,primary_key,start_ts)
end
end

opt commit
TiDB-->>PD: get ts as commit_ts
TiDB-->>TiKV: commit primary with commit_ts
loop send commit to each region in [](region,keys) parallelly
TiDB->>TiKV: commit(keys,commit_ts)
end
end
end

TiDB-->>client: success
```
Comment on lines +20 to +69
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Mermaid diagram is a great addition. To enhance clarity and align with the documentation style guide, I've made several improvements:

  • Corrected a typo from excute to execute.
  • Improved the descriptions to be more formal and descriptive (e.g., do read to Read operation).
  • Used consistent capitalization for actions.
  • Simplified complex descriptions to make the flow easier to follow (e.g., for all keys need to write,choose first one as primary to Select a primary key from all keys to be written).
  • Made the two phases of the commit process more explicit (Phase 1: Prewrite, Phase 2: Commit).
  • Corrected arrow types for requests to PD and TiKV to better reflect synchronous operations.

These changes make the diagram more professional and easier for new users to understand, as per the style guide's principle of clarity.

---
title: 2PC in TiDB
---
sequenceDiagram
    participant client
    participant TiDB
    participant PD
    participant TiKV

    client->>TiDB: BEGIN
    TiDB->>PD: Get timestamp as start_ts

    loop Execute SQL statements
        alt Read operation
            TiDB->>PD: Get region from PD (or cache)
            TiDB->>TiKV: Get data from TiKV (or cache) with start_ts
            TiDB-->>client: Return read result
        end
        alt Write operation
            TiDB-->>TiDB: Write to TiDB memory buffer
            TiDB-->>client: Return write result
        end
    end

    client->>TiDB: COMMIT

    opt 2PC (Two-Phase Commit)
        TiDB-->>TiDB: Select a primary key from all keys to be written
        TiDB->>PD: Locate region for each key
        TiDB-->>TiDB: Group keys by region

        opt Phase 1: Prewrite
            TiDB->>TiKV: Prewrite primary key with start_ts
            loop For each region
                TiDB->>TiKV: Prewrite secondary keys in parallel
            end
        end

        opt Phase 2: Commit
            TiDB->>PD: Get timestamp as commit_ts
            TiDB->>TiKV: Commit primary key with commit_ts
            loop For each region
                TiDB->>TiKV: Commit secondary keys in parallel
            end
        end
    end

    TiDB-->>client: Success
References
  1. The documentation should be clear, simple, and easy to understand for users. The suggested changes improve the clarity and readability of the sequence diagram. (link)
  2. The documentation should have a logical flow and clear sentence structure. The suggested changes improve the descriptions of the steps in the diagram. (link)
  3. If something might confuse a new user, suggest a reword. The original diagram's text was somewhat cryptic and could be confusing. The suggested changes make it more accessible. (link)


1. The client begins a transaction.

Expand Down
Loading