TiDB: A Distributed SQL Database That Splits Compute and Storage

The problem TiDB targets: single-node ceilings and data silos

TiDB is built for workloads that outgrow a single MySQL instance. The README frames it as a database for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. The core pitch is that you do not have to choose between a transactional database and an analytical one, and you do not have to manually shard your data. The intended user is a team that expects rapid, uneven growth and wants to avoid the operational ceiling of a vertical scale-up. TiDB also targets organizations that want to run analytics on the same data as their transactions, without ETL into a separate warehouse. If your data fits on one machine and your query patterns are simple, TiDB is overkill. But for a system that needs to scale past that point, it offers a path that does not involve rewriting your application for a new query language.

Architecture: separating compute from storage with Raft and Multi-Raft

The README describes a clear separation between computing and storage. The TiDB Server layer handles query execution and coordinates across two storage engines. TiKV is the row-based engine that stores transactional data. TiFlash is a columnar engine that replicates data from TiKV using the Multi-Raft Learner protocol, so the columnar copy stays consistent with the row-based original in real time. The two engines are not independent silos; the TiDB Server decides which engine to use for each query. This is the HTAP mechanism: you can run transactional workloads on TiKV and analytical queries on TiFlash, all through the same SQL interface. The Raft consensus protocol provides high availability by storing multiple replicas and committing transactions only after a majority of replicas acknowledge the write. That is a concrete trade-off: every write pays a replication cost, which is the price of automatic failover. The architecture also means you can scale compute and storage independently, adding TiDB Server nodes for query load and TiKV or TiFlash nodes for data capacity or analytical performance.

Getting started: playground, Kubernetes, or managed cloud

The README points to three deployment paths. For a local test, you use the quick start guide to deploy a playground cluster, which is the fastest way to see the system in action without provisioning real infrastructure. For production in your own environment, TiDB Operator manages clusters on Kubernetes, which is the recommended self-managed route. The third option is TiDB Cloud, a fully managed service with a free plan that requires no credit card. The README recommends TiDB Cloud for most users, which is a notable stance for an open-source project. The implication is that running a distributed database yourself is complex enough that PingCAP would rather you pay for the managed version. For an engineer evaluating adoption, this matters: the open-source core is real, but the operational burden is shifted to a commercial service in many cases. The quick start also mentions using a MySQL driver or ORM to build an app, which is the compatibility promise in practice.

MySQL compatibility: the migration promise and its limits

TiDB claims compatibility with MySQL 8.0, allowing you to use familiar protocols, frameworks, and tools. The README says you can migrate applications without changing code or with minimal modifications. That is a strong promise, and it is the main reason many teams consider TiDB in the first place. The compatibility is not complete, however. The README links to a detailed MySQL compatibility document, which is where you would find the gaps. In practice, you should expect differences in edge cases like index behavior, window functions, and system variables. The migration tools mentioned in the README help move data, but they do not guarantee that every SQL statement in your application behaves identically. The honest assessment is that TiDB is a wire-compatible MySQL alternative for common CRUD and analytical queries, but you should run your own test suite against a playground cluster before assuming a drop-in replacement. The risk is low for typical applications, but it is not zero.

HTAP and vector search: what the two-engine design enables

The HTAP feature is the most distinctive part of TiDB. Most databases force you to choose between row-oriented storage for writes and column-oriented storage for analytics. TiDB runs both, with TiFlash continuously replicating from TiKV. This means you can run analytical queries on fresh data without an ETL pipeline. The README also lists vector search as a feature, pointing to a separate overview document. That is a recent addition, aimed at the agentic workload trend mentioned in the project description. Vector search in a SQL database is interesting because it lets you combine semantic search with traditional relational queries in one system. However, the README does not provide details on the vector index implementation, distance functions, or performance characteristics. If vector search is a primary requirement, you should evaluate it separately. The HTAP promise is more concrete: you get real-time analytics on transactional data, but you pay for it with additional storage and replication overhead for TiFlash.

Limitations and failure modes: when TiDB is the wrong tool

TiDB's complexity is its main limitation. A distributed database with three separate components (TiDB Server, TiKV, TiFlash) is inherently harder to operate than a single MySQL instance. The README does not hide this; it recommends TiDB Cloud for most users, which is an admission that self-managing is not trivial. The Raft consensus protocol adds latency on every write, because a transaction must reach a majority of replicas before committing. For workloads that require extremely low write latency on a single node, TiDB will be slower than a standalone database. Another failure mode is the MySQL compatibility gap. If your application relies on stored procedures, triggers, or exotic SQL features, you may hit unsupported behavior. The README does not list these limitations explicitly, but the existence of a compatibility guide implies them. Finally, for small datasets that fit on one machine, the operational overhead of a distributed cluster is wasted. TiDB is a tool for scale, not for simplicity.

Alternatives: CockroachDB and single-node MySQL with replicas

The most direct alternative is CockroachDB, another distributed SQL database that also uses the Raft protocol for replication and offers horizontal scaling. The key difference is that CockroachDB does not provide a separate columnar engine for HTAP; it focuses on transactional workloads with a single storage engine. If your priority is pure OLTP with strong consistency and you do not need analytics on the same data, CockroachDB may be simpler. On the other end, if you only need high availability and your dataset fits on one primary node, a standard MySQL setup with replication and automated failover (for example, using Orchestrator or a cloud-managed MySQL service) gives you ACID and familiar tooling without the distributed complexity. The trade-off is that you lose online horizontal scaling and the HTAP capability. TiDB's differentiator is the combination of both, but that comes at the cost of more moving parts.

Licensing, maintenance, and upgrade considerations

TiDB is licensed under Apache-2.0, which is permissive and allows commercial use, modification, and distribution without copyleft obligations. The README emphasizes that all source code, including enterprise-grade features, is available under this license. That is a meaningful advantage over some other distributed databases that use a source-available license. The project is actively maintained, with recent releases like v8.5.8 in August 2026 and a regular cadence of patch releases. The maintenance cost for a self-managed cluster is significant: you must handle upgrades, backups, monitoring, and scaling of three different components. The README points to TiDB Operator for Kubernetes, which automates some of this, but it does not eliminate the need for operational expertise. The upgrade path is documented through the release notes, but you should test upgrades in a staging environment. The Apache-2.0 license also means you can fork and modify the code, but doing so would put you on your own for support, which is a risk for production adoption.

Editorial conclusion

Adopt TiDB if you need a MySQL-compatible distributed database that scales horizontally without sharding and want the option of real-time analytics on the same data. It suits teams already on Kubernetes or willing to use TiDB Cloud. Avoid it if your workload fits a single node and you do not need online scaling or HTAP; the operational overhead of a multi-component cluster is not justified for a simple OLTP app. Before committing, verify your SQL feature usage against TiDB's MySQL compatibility list, test the migration tools with your schema, and confirm the Raft replication overhead meets your latency targets.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes