cloudparts

TiDB

A distributed SQL database that speaks the MySQL protocol, stores rows in TiKV, a Raft-replicated key-value store, and can keep a columnar copy in TiFlash for analytics on live data.

What it is
Relational databases,NewSQL and distributed SQL
Type
Open source
Made by
PingCAP
License
Apache 2.0; TiDB Cloud is a proprietary managed service
Facts checked
24 October 2026
Website Source code

What it is

TiDB splits a database into separate services. TiDB servers are stateless SQL nodes: they speak the MySQL protocol (on port 4000 by default), parse and plan queries, and store nothing, so you add them behind a load balancer as traffic grows. TiKV, written in Rust, stores the data as key-value pairs in one sorted keyspace, cut into Regions of up to 256 MiB by default. Each Region has three replicas by default that form a Raft group, and a write succeeds once a majority has it; on each node the data sits in RocksDB. PD (Placement Driver), a cluster of at least three nodes, keeps the map of which Region lives where, moves and splits Regions to balance load, and hands out timestamps (TSO): a physical time in milliseconds plus a logical counter.

Transactions follow Google’s Percolator model: a transaction reads at a start timestamp from PD, writes locks and new versions to every Region it touches in a two-phase commit, and becomes visible at a commit timestamp. Every key is stored with its version, newest first (MVCC). New clusters use pessimistic locking, as MySQL does, and TiDB provides snapshot isolation, which it reports as MySQL’s REPEATABLE-READ; READ-COMMITTED is also available, but SERIALIZABLE returns an error. For analytics you add TiFlash replicas to a table: TiFlash is a columnar store that follows TiKV as a Raft learner, asynchronously but with consistent reads, and the optimizer decides per query whether to read rows from TiKV, columns from TiFlash, or both, running large joins and aggregates across TiFlash nodes in MPP mode. TiCDC streams changes to MySQL, Kafka (as Canal-JSON, Avro or Debezium events) and object storage.

The whole database, enterprise features included, is Apache 2.0, and PingCAP sells TiDB Cloud. Its Starter plan is multi-tenant and autoscaling, with up to five free instances per organization, each with 5 GiB of row storage, 5 GiB of columnar storage and 50 million Request Units a month; Essential starts at $400 a month and Dedicated, with separately sized TiDB, TiKV and TiFlash nodes, at $1,376. Since October 2025 the cloud plans have been moving to TiDB X, a new architecture that keeps data in object storage and caches it on compute nodes; PingCAP says it will open-source TiDB X’s core by the end of 2026. In October 2026 it opened a public preview of PostgreSQL compatibility on Starter. Self-managed, the current long-term-support line is 8.5 (8.5.8, August 2026); 9.0 has only had a beta.

Why teams pick it

  • MySQL-compatible: MySQL drivers, ORMs and tools connect unchanged, and TiDB follows MySQL 8.0 syntax, including foreign keys (generally available since 8.5)
  • Grows without manual sharding: Regions split and move on their own, and SQL, storage and analytics nodes scale independently
  • Analytics on live data: a TiFlash replica is one ALTER TABLE away, stays consistent with the row store, and the optimizer chooses it per query
  • Fully Apache 2.0, runs on Kubernetes through TiDB Operator, and starts locally with one tiup playground command

Watch out for

  • Not all of MySQL: no stored procedures, triggers, events, user-defined functions, SPATIAL types, XA transactions, descending indexes or SKIP LOCKED, and FULLTEXT indexes are not usable on self-managed clusters
  • Snapshot isolation, not serializable: write skew is possible, and optimistic transactions can fail at commit where MySQL would succeed
  • Sequential keys such as AUTO_INCREMENT send every insert to the last Region, a write hotspot; the docs recommend AUTO_RANDOM or SHARD_ROW_ID_BITS, which give up ordered IDs
  • A transaction is capped at 100 MB by default (configurable up to 1 TB) and a row at 6 MB, a TiDB server can need two to three times a transaction’s size in memory, and a minimal production cluster runs three kinds of service, each with several nodes

Good for

Specs

Compare with alternatives →
Data model
Relational tables over one sorted key-value keyspace (TiKV)
Query language
MySQL-compatible SQL (MySQL 8.0 syntax)
Client protocol
MySQL protocol (port 4000 by default)
Transactions
Any rows across Regions, Percolator-style two-phase commit; 100 MB by default
Default isolation
Snapshot isolation, reported as REPEATABLE-READ; no serializable
Consistency
Snapshot reads at timestamps handed out by PD (TSO)
How it scales
Automatic: Regions up to 256 MiB split and rebalance; SQL, storage and TiFlash nodes scale separately
Replication
Raft per Region, three replicas by default; TiFlash replicas as Raft learners
Storage engine
RocksDB on each TiKV node
Storage format
Rows in TiKV; optional columnar replicas in TiFlash
Written in
Go (SQL layer) and Rust (TiKV)
Ways to run it
Self-hosted with TiUP, TiDB Operator on Kubernetes, or TiDB Cloud
Pricing model
TiDB Cloud: free Starter instances within limits; Essential from $400 a month, Dedicated from $1,376

Alternatives

What all relational databases have in common →Compare side by side →
CockroachDBCommercialAlso good for sql past one serverA distributed SQL database that speaks the PostgreSQL wire protocol, replicates every slice of data with Raft and keeps transactions serializable across nodes and regions.FoundationDBOpen sourceAn ordered, distributed key-value store with strictly serializable ACID transactions across the whole cluster, built as a small core that other databases are layered on.YugabyteDBOpen sourceAlso good for sql past one serverA distributed SQL database that runs PostgreSQL’s own query layer on top of DocDB, a sharded, Raft-replicated storage engine built on RocksDB.VitessOpen sourceAlso good for sql past one serverA proxy layer, born at YouTube, that shards MySQL across many servers while the app still sees one database.MySQLOpen sourceThe long-standing open-source SQL database behind much of the web, built on the InnoDB engine.+1 MariaDBAlibaba Cloud PolarDBCommercialAlso good for sql past one serverAlibaba Cloud’s cloud-native relational databases: MySQL- and PostgreSQL-compatible clusters whose compute nodes share one copy of the data on distributed storage, plus PolarDB-X, a distributed MySQL-compatible edition.MariaDBOpen sourceThe open-source fork of MySQL started by MySQL’s original developers in 2009: the same protocol and most of the same SQL, with its own storage engines, built-in Galera clustering and features MySQL lacks.PlanetScaleCommercialAlso good for sql past one serverManaged MySQL on Vitess and managed Postgres, with schema changes shipped through branches and deploy requests.

How it fits with other technologies

A local cluster, a hotspot-free table and a columnar replica · bash

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
tiup playground   # one each of TiDB, PD, TiKV and TiFlash, on the latest version

mysql --host 127.0.0.1 --port 4000 -u root <<'SQL'
CREATE DATABASE shop; USE shop;
-- AUTO_RANDOM scatters new ids across Regions instead of appending to the last one
CREATE TABLE orders (
  id          BIGINT PRIMARY KEY AUTO_RANDOM,
  customer_id BIGINT NOT NULL,
  total       DECIMAL(10,2),
  placed_at   DATETIME NOT NULL
);
-- a columnar copy in TiFlash, kept in step through Raft
ALTER TABLE orders SET TIFLASH REPLICA 1;
SELECT @@transaction_isolation;   -- REPEATABLE-READ (snapshot isolation)
EXPLAIN SELECT customer_id, SUM(total) FROM orders GROUP BY customer_id;  -- may read TiFlash
SQL

See it in a real stack

No architecture uses TiDB yet. Drop it into the playground and wire it up yourself.Open playground →

Compared side by side

FoundationDB, CockroachDB or TiDB?
Where it came from2015–2026

At Wandou Labs, a Chinese Android app store, Ed Huang wrote Codis, an open-source tool that sharded and rebalanced Redis automatically. Behind it sat a large sharded MySQL cluster, where re-sharding was painful and the application had to give up transactions and complex queries across shards. In 2015 he, Max Liu and Dylan Cui, who had worked together at Wandou Labs, founded PingCAP in Beijing to build a database that behaves like one MySQL server but spreads data and transactions across many machines, drawing on Google’s Spanner and F1 papers. A first version ran on HBase and was too slow, so they built their own storage, TiKV. TiDB’s repository opened in September 2015 and TiKV’s on the last day of that year; TiKV’s design drew on Bigtable, Spanner and Percolator and on the Raft consensus algorithm.

TiDB 1.0 shipped on 16 October 2017, already running in production at more than 30 companies in Asia, including Mobike. PingCAP donated TiKV to the CNCF in 2018, and it graduated in 2020. TiDB 4.0, in May 2020, added TiFlash, a columnar engine that made TiDB a database for transactions and analytics at once. The company later set up its headquarters in Sunnyvale, California, and built TiDB Cloud; in October 2025 it announced TiDB X, an object-storage architecture for the cloud service, and in October 2026 a PostgreSQL-compatible preview.

Why it’s built this way

Speak MySQL’s protocol instead of inventing a new interface
The people who needed to scale were running MySQL shards. Matching the protocol and syntax let them move applications, drivers and tools with little or no code change.
Separate SQL, storage and placement into different services
Stateless SQL nodes can be added or replaced freely, TiKV can be used on its own as a transactional key-value store, and one placement service can balance Regions with a cluster-wide view.
A central timestamp oracle instead of synchronized clocks
Percolator-style transactions need timestamps every node agrees on. Handing them out from PD avoids depending on clock accuracy, at the cost of a round trip to PD for every transaction.
A columnar replica fed by Raft rather than an ETL pipeline
Copying data to a warehouse adds delay and a second system. A TiFlash learner receives the same Raft log as the row replicas, so analytics read fresh, consistent data without slowing the writes.

Timeline

  1. 2015

    PingCAP founded; TiDB repository opens in September

  2. 2017

    TiDB 1.0 released on 16 October

  3. 2018

    TiKV joins the CNCF as an incubating project

  4. 2019

    3.0.8 makes pessimistic transactions the default

  5. 2020

    TiDB 4.0 adds TiFlash; TiKV graduates from the CNCF

  6. 2024

    TiDB 8.5, the current long-term-support line, ships in December

  7. 2025

    TiDB X, an object-storage architecture for TiDB Cloud, announced

  8. 2026

    PostgreSQL-compatible preview on TiDB Cloud Starter

Sources17 · facts checked 24 October 2026

Improve this page on GitHub