Data Platforms 06 Oct 2026 38 min read

Correctness, then cost, then neighbours: ten years of TiDB, read from its own design record

What ten years of one distributed SQL database's design documents, RFCs, release notes and critical bug reports say about the order in which a shared transactional system's constraints arrive, and which of its redesigns actually reached users.

Read the field guide → The evidence ledger

PingCAP has published a dated design document or RFC for nearly every substantial change to TiDB and TiKV since 2018, plus a release note for every version since 2017. Read in order, that record shows the binding constraint moving from MySQL compatibility to the local cost of the replication guarantee to isolation between tenants, with the governance plane retrofitted into a mature serving path from 2021 onward. A reader leaves able to argue, with dates and shipped defaults, where their own system is in that sequence, which local guarantees they are paying for twice, and how to tell a vendor's shipped architecture from its published one.

The finding that surprised me

The storage redesign that was meant to take clusters from terabytes to petabytes never appears in a release note after October 2023; what users actually received is a default region split size raised from 96 MB to 256 MB in v8.3.0, while the workaround the redesign was meant to retire is still enabled by default in the shipped configuration.

What you get out of it

The design record's themes move in one direction: compatibility (2017-2020), the local cost of the guarantee (2021-2023), tenancy and admission control (2023-2026), with no governance document at all before 2021 and four of the ten 2026 documents in that class.
Four separate RFCs delete a local duplicate of a guarantee the quorum already provides (unreplicated locks, no key-value WAL, apply before persistence, throttling above the engine), each paired with a named compensation; the compensations are where the remaining complexity sits.
Of 148 release-note fixes for data or index inconsistency, the largest class by far (36) is the online schema-change path, and the recurring trigger is an ownership change during a long index build rather than anything in the serving path.
Isolation granularity was argued out in public: the region-level fairness RFC was closed unmerged in April 2026 with three reviewers preferring query-level control, which is what shipped as a per-statement in-flight limit of 15 requests per store.
The November 2025 active-active design gives up global transactional consistency between clusters for last write wins, a decade after the system claimed Spanner-style external consistency, and needed soft deletes so a tombstone could still be compared.

Scope

Why this, now. The 2025 and 2026 documents in this repository are the first to give up cross-cluster transactional consistency for last-write-wins and to organise observability around the billing unit, which makes the decade's direction legible in a way it was not a year ago.

What it does not cover. TiDB Cloud and next-generation cloud internals, which are not in the open repositories; any comparison with other distributed SQL databases; and every source published outside a code host, because this session's network reached GitHub only, so there are no engineering blog posts, conference talks, independent benchmarks or customer incident reports and the failure section is built from severity-critical bug reports instead.

Open the field guide → Self-contained: it loads nothing at read time, follows your system theme, and prints cleanly.

Keep digging

Other field guides

Data Platforms

Correctness, then cost, then neighbours: ten years of TiDB, read from its own design record

What you get out of it

Scope

Other field guides

The shim outlives the migration: ten years of Sentry, read from its own deletions

There is no neutral identifier

Every backend you add is a six-year promise: ten years of Grafana Labs in git