*: add detailed intro to the TiDB X architecture #22245
Open
+119
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ti-chi-bot
bot
added
the
do-not-merge/work-in-progress
ti-chi-bot
bot
added
contribution
|
Hi @dbsid. Thanks for your PR. I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
ti-chi-bot
bot
added
the
missing-translation-status
Contributor
Summary of ChangesHello @dbsid, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces detailed documentation for the new TiDB X architecture, outlining its fundamental shift towards a cloud-native, 'Share-Everything' design. It addresses limitations of the classic TiDB architecture by implementing innovations such as object storage as the single source of truth, a 'Compute and Compute' separation for workload isolation, and an LSM Forest storage engine, all aimed at enhancing scalability, stability, cost-effectiveness, and performance predictability. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
ti-chi-bot
bot
added
the
size/L
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a new documentation page for the TiDB X architecture. The content provides a good high-level overview of the new architecture, its motivations, and key innovations. My review focuses on improving clarity, correcting some typos and grammatical errors, and ensuring consistency in terminology, as per the repository's style guide. I've provided several suggestions to enhance readability and technical accuracy.
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
likidu
reviewed
Dec 30, 2025
likidu
reviewed
Dec 30, 2025
likidu
reviewed
Dec 30, 2025
Member
Review CommentsTerminology Suggestion: Share-Everything → Shared-StorageThe term Share-Everything is imprecise and creates an awkward comparison (as @likidu noted - comparing a distributed database to an SOA is not apples-to-apples). Recommendation: Consider using Shared-Storage instead:
Alternative framing for the intro:
Structural Issues
Content Issues
PR DescriptionPlease fill in the required What is changed, added or deleted? section before moving out of draft. Overall the content is well-structured and provides good technical depth. The diagrams help illustrate the architectural differences clearly. |
ti-chi-bot
bot
removed
the
missing-translation-status
Member
|
/ok-to-test |
ti-chi-bot
bot
added
size/XXL
ti-chi-bot
bot
added
size/L
ti-chi-bot
bot
added
size/XXL
ti-chi-bot
bot
added
size/L
Frank945946
reviewed
Jan 12, 2026
tidb-cloud/tidb-x-architecture.md
Outdated
|
|
||
| The architecture diagram highlights a sophisticated separation of duties, ensuring that different types of work do not interfere with each other. The top "Isolated SQL Layer" consists of separate groups of compute nodes, which allows for multi-tenancy or workload isolation where different applications can have dedicated compute resources while sharing the same underlying data. Beneath this, the "Shared Services" layer breaks down heavy database tasks into independent microservices for operations like compaction, analyze, and DDL. By offloading expensive background operations—such as adding an index, Online DDL, or massive data imports—to the Shared Services layer, the system ensures these heavy jobs never compete for CPU or memory with the "Compute" nodes serving online user traffic. This guarantees predictable performance for critical applications and allows each component—Gateway, SQL Compute, Cache, and Background Services—to scale independently based on specific bottlenecks. | ||
|
|
||
| # Key innovations of TiDB X |
Collaborator
There was a problem hiding this comment.
There are some comparisons with classic TiDB in this section, such as “6TB+ data per TiKV node or 200k+ SST files,” which are duplicated in the section “The Architectural Ceiling: Challenges Hard to Overcome.” It would be better to remove the redundant descriptions.
|
|
||
| ## Rapid Elastic Scalability (5x-10x Faster) | ||
|
|
||
| In TiDB X, data resides in shared object storage with fully isolated LSM-trees for each Region. The system eliminates the need for physical data migration or compaction when adding or removing TiKV nodes. The result is a 5x–10x improvement in scaling speed compared to classic TiDB, maintaining stable latency for online traffic. |
Collaborator
There was a problem hiding this comment.
There are many key advantages. It is recommended to end with a summary section that includes a comparison between TiDB Classic and TiDB X in key areas, making it easier for users to remember.
Co-authored-by: Frank945946 <[email protected]>
lilin90
reviewed
Jan 14, 2026
Member
lilin90
left a comment
lilin90
left a comment
There was a problem hiding this comment.
I'll continue my review soon.
| @@ -0,0 +1,111 @@ | |||
| --- | |||
| title: TiDB X Architecture | |||
| summary: Learn how TiDB X's shared-storage architecture delivers cloud-native scalability and cost optimization | |||
Member
There was a problem hiding this comment.
Suggested change
| summary: Learn how TiDB X's shared-storage architecture delivers cloud-native scalability and cost optimization | |
| summary: Learn how the shared-storage, cloud-native TiDB X architecture delivers elastic scalability, predictable performance, and optimized total cost of ownership. |
|
|
||
| # TiDB X Architecture | ||
|
|
||
| TiDB X represents a fundamental architectural evolution from classic TiDB's Shared-Nothing design to a cloud-native Shared-Storage architecture. By leveraging object storage as the single source of truth, TiDB X introduces "Separation of Compute and Compute" design that isolates online transactional workloads from heavy background tasks. This architecture enables elastic scalability, predictable performance, and optimized Total Cost of Ownership (TCO) for AI-era workloads. |
Member
There was a problem hiding this comment.
Reason:
- Since this doc is about intro to TiDB X, the first intro should tell what it is clearly to help users quickly get it if they don't want to read details.
- The phrase "single source of truth" is marketing-oriented, not recommended in official docs.
- Clarify what is being separated (compute workloads), not just repeating the slogan.
- Use lowercase “total cost of ownership (TCO)” on first occurrence (common style-guide practice).
Definition reference:
- https://www.pingcap.com/press-release/pingcap-launches-tidb-x-new-ai-capabilities/
- https://www.pingcap.com/blog/introducing-tidb-x-a-new-foundation-distributed-sql-ai-era/
Suggested change
| TiDB X represents a fundamental architectural evolution from classic TiDB's Shared-Nothing design to a cloud-native Shared-Storage architecture. By leveraging object storage as the single source of truth, TiDB X introduces "Separation of Compute and Compute" design that isolates online transactional workloads from heavy background tasks. This architecture enables elastic scalability, predictable performance, and optimized Total Cost of Ownership (TCO) for AI-era workloads. | |
| TiDB X is a new distributed SQL architecture that makes cloud-native object storage the backbone of TiDB. This architecture enables elastic scalability, predictable performance, and optimized total cost of ownership (TCO) for AI-era workloads. | |
| TiDB X represents a fundamental evolution from [classic TiDB](/tidb-architecture.md)'s shared-nothing architecture to a cloud-native shared-storage architecture. By leveraging object storage as the shared persistent storage layer, TiDB X introduces a separation of compute workloads that isolates online transactional processing from resource-intensive background tasks. |
lilin90
reviewed
Jan 16, 2026
|
|
||
| TiDB X represents a fundamental architectural evolution from classic TiDB's Shared-Nothing design to a cloud-native Shared-Storage architecture. By leveraging object storage as the single source of truth, TiDB X introduces "Separation of Compute and Compute" design that isolates online transactional workloads from heavy background tasks. This architecture enables elastic scalability, predictable performance, and optimized Total Cost of Ownership (TCO) for AI-era workloads. | ||
|
|
||
| This document details the challenges of the classic TiDB architecture, the architecture of TiDB X, and its key innovations. |
Member
There was a problem hiding this comment.
Suggested change
| This document details the challenges of the classic TiDB architecture, the architecture of TiDB X, and its key innovations. | |
| This document introduces the TiDB X architecture, explains the motivation behind TiDB X, and describes the key innovations compared with the classic TiDB architecture. |
lilin90
reviewed
Jan 16, 2026
lilin90
reviewed
Jan 19, 2026
|
|
||
| ### Strengths of classic TiDB | ||
|
|
||
| The "Shared-Nothing" architecture of classic TiDB effectively overcame the limitations of traditional monolithic databases. By decoupling compute from storage and utilizing the Raft consensus algorithm, it delivered a level of resilience and scale that defined the modern NewSQL era. |
Member
There was a problem hiding this comment.
- Use capitalized letters only when necessary.
- Use present tense in most cases. Since classic TiDB still exists and serves customers, using the present tense is ok.
Suggested change
| The "Shared-Nothing" architecture of classic TiDB effectively overcame the limitations of traditional monolithic databases. By decoupling compute from storage and utilizing the Raft consensus algorithm, it delivered a level of resilience and scale that defined the modern NewSQL era. | |
| The shared-nothing architecture of classic TiDB addresses the limitations of traditional monolithic databases. By decoupling compute from storage and utilizing the Raft consensus algorithm, it provides the resilience and scalability required for distributed SQL workloads. |
|
|
||
| The "Shared-Nothing" architecture of classic TiDB effectively overcame the limitations of traditional monolithic databases. By decoupling compute from storage and utilizing the Raft consensus algorithm, it delivered a level of resilience and scale that defined the modern NewSQL era. | ||
|
|
||
| Its success was built on several foundational strengths: |
Member
There was a problem hiding this comment.
Suggested change
| Its success was built on several foundational strengths: | |
| The classic TiDB architecture is built on several foundational capabilities: |
|
|
||
| Its success was built on several foundational strengths: | ||
|
|
||
| - Massive Horizontal Scalability: Classic TiDB allowes businesses to scale both read and write performance linearly with their workload, reaching millions of QPS while supporting massive clusters with over 1 PiB of data and tens of millions of tables. |
Member
There was a problem hiding this comment.
- Limit the use of marketing tone.
- Make sentences easy to read.
Suggested change
| - Massive Horizontal Scalability: Classic TiDB allowes businesses to scale both read and write performance linearly with their workload, reaching millions of QPS while supporting massive clusters with over 1 PiB of data and tens of millions of tables. | |
| - Horizontal scalability: It supports linear scaling for both read and write performance. Clusters can scale to handle millions of queries per second (QPS) and manage over 1 PiB of data across tens of millions of tables. |
| Its success was built on several foundational strengths: | ||
|
|
||
| - Massive Horizontal Scalability: Classic TiDB allowes businesses to scale both read and write performance linearly with their workload, reaching millions of QPS while supporting massive clusters with over 1 PiB of data and tens of millions of tables. | ||
| - True HTAP Capabilities: It unified transactional and analytical processing. By pushing down heavy aggregation and join operations to TiFlash (the columnar engine), it provided predictable, real-time analytics on fresh transactional data without complex ETL pipelines. |
Member
There was a problem hiding this comment.
Suggested change
| - True HTAP Capabilities: It unified transactional and analytical processing. By pushing down heavy aggregation and join operations to TiFlash (the columnar engine), it provided predictable, real-time analytics on fresh transactional data without complex ETL pipelines. | |
| - Hybrid Transactional and Analytical Processing (HTAP): It unifies transactional and analytical workloads. By pushing down heavy aggregation and join operations to TiFlash (the columnar storage engine), it provides predictable, real-time analytics on fresh transactional data without complex ETL pipelines. |
|
|
||
| - Massive Horizontal Scalability: Classic TiDB allowes businesses to scale both read and write performance linearly with their workload, reaching millions of QPS while supporting massive clusters with over 1 PiB of data and tens of millions of tables. | ||
| - True HTAP Capabilities: It unified transactional and analytical processing. By pushing down heavy aggregation and join operations to TiFlash (the columnar engine), it provided predictable, real-time analytics on fresh transactional data without complex ETL pipelines. | ||
| - Non-Blocking Operations: Its implementation of Fully Online DDL meant that schema changes were non-blocking for reads and writes, allowing businesses to evolve their data models with minimal impact on latency or uptime. |
Member
There was a problem hiding this comment.
Suggested change
| - Non-Blocking Operations: Its implementation of Fully Online DDL meant that schema changes were non-blocking for reads and writes, allowing businesses to evolve their data models with minimal impact on latency or uptime. | |
| - Non-blocking schema changes: It utilizes a fully online DDL implementation. Schema changes do not block reads or writes, allowing data models to evolve with minimal impact on application latency or availability. |
Comment on lines
+25
to
+26
| - Always-Online Availability: The architecture supported seamless cluster upgrades and scaling operations (up/down), ensuring critical services remained online during maintenance. | ||
| - Freedom from Lock-in: As an open-source solution supporting AWS, GCP, and Azure, it offered true cloud neutrality, preventing vendor lock-in. |
Member
There was a problem hiding this comment.
Suggested change
| - Always-Online Availability: The architecture supported seamless cluster upgrades and scaling operations (up/down), ensuring critical services remained online during maintenance. | |
| - Freedom from Lock-in: As an open-source solution supporting AWS, GCP, and Azure, it offered true cloud neutrality, preventing vendor lock-in. | |
| - High availability: It supports seamless cluster upgrades and scaling operations. This ensures that critical services remain accessible during maintenance or resource adjustment. | |
| - Multi-cloud support: It operates as an open-source solution with support for Amazon Web Services (AWS), Google Cloud, and Microsoft Azure. This provides cloud neutrality without vendor lock-in. |
lilin90
reviewed
Jan 19, 2026
lilin90
reviewed
Jan 19, 2026
lilin90
reviewed
Jan 19, 2026
|
|
||
| ### Challenges of classic TiDB | ||
|
|
||
| Despite these massive achievements, the "Shared-Nothing" architecture of classic TiDB, where storage and compute are tightly coupled on local nodes—eventually hit physical limitations in extreme large-scale environments. As data volumes exploded and cloud-native expectations evolved, inherent structural challenges emerged that were difficult to resolve without a fundamental redesign. |
Member
There was a problem hiding this comment.
Suggested change
| Despite these massive achievements, the "Shared-Nothing" architecture of classic TiDB, where storage and compute are tightly coupled on local nodes—eventually hit physical limitations in extreme large-scale environments. As data volumes exploded and cloud-native expectations evolved, inherent structural challenges emerged that were difficult to resolve without a fundamental redesign. | |
| While the shared-nothing architecture of classic TiDB provides high resilience, the tight coupling of storage and compute on local nodes introduces limitations in extreme large-scale environments. As data volumes grow and cloud-native requirements evolve, several structural challenges emerge. |
Comment on lines
+32
to
+34
| - Scalability limitations: In classic TiDB, scaling out (adding nodes) or scaling in (removing nodes) requires physically copying massive amounts of data (SST files) between nodes. This process is time-consuming for large datasets and can impact online traffic due to the heavy CPU and I/O required to move data. | ||
|
|
||
| The underlying storage engine (RocksDB) in classic TiDB uses a single LSM-tree protected by a global mutex. This creates a scalability ceiling where the system struggles to handle large datasets (e.g., 6TB+ data or 200k+ SST files per TiKV node), preventing it from utilizing the full capacity of the hardware. |
Member
There was a problem hiding this comment.
Suggested change
| - Scalability limitations: In classic TiDB, scaling out (adding nodes) or scaling in (removing nodes) requires physically copying massive amounts of data (SST files) between nodes. This process is time-consuming for large datasets and can impact online traffic due to the heavy CPU and I/O required to move data. | |
| The underlying storage engine (RocksDB) in classic TiDB uses a single LSM-tree protected by a global mutex. This creates a scalability ceiling where the system struggles to handle large datasets (e.g., 6TB+ data or 200k+ SST files per TiKV node), preventing it from utilizing the full capacity of the hardware. | |
| - **Scalability limitations** | |
| - Data movement overhead: In classic TiDB, scaling out (adding nodes) or scaling in (removing nodes) operations require physical movement of SST files between nodes. For large datasets, this process is time-consuming and can degrade online traffic performance due to heavy CPU and I/O consumption during data movement. | |
| - Storage engine bottleneck: The underlying RocksDB storage engine in classic TiDB uses a single LSM-tree protected by a global mutex. This design creates a scalability ceiling where the system struggles to handle large datasets (for example, over 6 TiB of data or 200,000 SST files per TiKV node), preventing the system from fully utilizing the hardware capacity. |
lilin90
reviewed
Jan 19, 2026
Comment on lines
+36
to
+38
| - Stability and performance challenges: Heavy write traffic triggers massive local compaction jobs to merge SST files. In the Classic architecture, these compaction jobs run on the same TiKV nodes serving online traffic, consuming significant CPU and I/O resources and can impact the online traffic. | ||
|
|
||
| There is no physical isolation between logical regions and physical SST files. Operations like adding an index or moving a region (balancing) create compaction overhead that competes directly with user queries, leading to performance jitter. Under heavy write pressure, if the background compaction cannot keep up with the foreground write traffic, the system can trigger flow control mechanisms to protect the storage engine, which results in write throughput throttling and latency spikes for the application. |
Member
There was a problem hiding this comment.
Suggested change
| - Stability and performance challenges: Heavy write traffic triggers massive local compaction jobs to merge SST files. In the Classic architecture, these compaction jobs run on the same TiKV nodes serving online traffic, consuming significant CPU and I/O resources and can impact the online traffic. | |
| There is no physical isolation between logical regions and physical SST files. Operations like adding an index or moving a region (balancing) create compaction overhead that competes directly with user queries, leading to performance jitter. Under heavy write pressure, if the background compaction cannot keep up with the foreground write traffic, the system can trigger flow control mechanisms to protect the storage engine, which results in write throughput throttling and latency spikes for the application. | |
| - **Stability and performance interference** | |
| - Resource contention: Heavy write traffic triggers massive local compaction jobs to merge SST files. In classic TiDB, because these compaction jobs run on the same TiKV nodes serving online traffic, they compete for the same CPU and I/O resources, which might affect the online application. | |
| - Lack of physical isolation: There is no physical isolation between logical Regions and physical SST files. Operations like adding an index or moving a region (balancing) create compaction overhead that competes directly with user queries, leading to potential performance jitter. | |
| - Write throttling: Under heavy write pressure, if the background compaction cannot keep up with the foreground write traffic, the classic TiDB triggers flow control mechanisms to protect the storage engine. This results in write throughput throttling and latency spikes for the application. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
First-time contributors' checklist
What is changed, added or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?