TiDB

TiDB is a cloud-native, distributed SQL database that speaks the MySQL wire protocol while scaling horizontally across commodity hardware. It separates compute from storage, pairing a stateless SQL layer with TiKV (a row-based, Raft-replicated key-value store) and optionally TiFlash (a columnar replica engine), so the same cluster can serve low-latency transactional traffic and large analytical queries without ETL pipelines between separate systems.

Under the hood, TiDB uses a Percolator-derived two-phase commit protocol on top of Raft consensus to guarantee ACID transactions across nodes, and a cost-based optimizer that can push queries down to either the row store or the columnar replicas depending on shape. Applications built against MySQL drivers and ORMs can point at TiDB with little to no code change, while operators get automatic sharding, online schema changes, and multi-region replica placement without manual resharding.

As a Go module, the repository is really the source for the tidb-server binary and its supporting internals (the SQL parser, planner, executor, DDL engine, statistics subsystem, and storage drivers) rather than a library meant to be imported piecemeal into unrelated applications — most consumers run TiDB as a deployed database server (self-managed, via TiDB Operator on Kubernetes, or as the managed TiDB Cloud service) and talk to it over the standard MySQL protocol rather than importing its Go packages directly.

What You Get

• A MySQL-protocol-compatible SQL layer (tidb-server) that most existing MySQL drivers, ORMs, and tooling can connect to with little or no application code changes.
• Horizontal scaling of both compute and storage independently, with online schema changes and automatic data sharding instead of manual resharding.
• Distributed ACID transactions across nodes via a two-phase commit protocol layered on Raft consensus, so failures don’t compromise consistency.
• Built-in HTAP: TiKV serves row-based OLTP traffic while TiFlash maintains a real-time columnar replica for analytical queries, coordinated by the same optimizer.
• Multiple deployment paths — local playground, self-managed on bare metal/Kubernetes via TiDB Operator, or fully managed as TiDB Cloud.

Common Use Cases

• Replacing a sharded MySQL fleet with a single logical database that scales without application-level sharding logic.
• Running real-time analytics directly against operational data without a separate ETL pipeline into a data warehouse.
• Building globally distributed applications that need geo-aware replica placement and strong consistency guarantees.
• Migrating existing MySQL-backed applications to a horizontally scalable backend using standard MySQL drivers and migration tooling.
• Powering AI/agentic workloads that need unpredictable, bursty scale alongside transactional guarantees and vector search.

Under The Hood

Architecture TiDB is organized as a layered, modular monolith rooted at cmd/tidb-server/main.go, which wires together the SQL surface (pkg/server), session management (pkg/session), the parser (pkg/parser), planner and optimizer (pkg/planner), executor (pkg/executor), DDL engine (pkg/ddl), statistics subsystem (pkg/statistics), and storage drivers (pkg/store, with pkg/store/mockstore and pkg/store/driver bridging to TiKV/TiFlash over the kv abstraction). Query execution flows from protocol parsing through the planner’s logical/physical optimization phases into a Volcano-style executor that dispatches work either locally or via coprocessor push-down to TiKV/TiFlash; the domain package holds cluster-wide shared state (schema cache, statistics, bindings) that individual sessions read from. Swapping the core storage abstraction would ripple through kv, store/driver, and every executor that issues coprocessor requests, since nearly every subsystem is written against that interface rather than a concrete engine.

Tech Stack Written in Go (module targets Go 1.25) with an extensive dependency surface: github.com/pingcap/kvproto and github.com/pingcap/tipb for the wire protocols to TiKV/TiFlash, github.com/cockroachdb/pebble and in-house structures for local storage paths, go.etcd.io/etcd for cluster coordination, Prometheus client libraries and github.com/grafana/pyroscope-go for metrics/profiling, plus cloud SDKs (AWS, Azure, Alibaba, GCP) for backup/restore and object storage integrations. The build is dual-tracked through both a standard Go toolchain (Makefile) and Bazel (BUILD.bazel, WORKSPACE, MODULE.bazel) for reproducible CI builds, with Docker images (Dockerfile, Dockerfile.enterprise) for containerized deployment.

Code Quality The repository is extremely well-tested: over 1,600 _test.go files across pkg/, using testify/require for assertions alongside TiDB’s own testkit harness for SQL-level integration tests. .golangci.yml enables a strict linter set (staticcheck, gosec, errcheck, revive, bodyclose, prealloc, ineffassign, and more), and CI runs both Bazel-based build/lint pipelines and dedicated integration-test workflows (BR, Dumpling) via GitHub Actions and a Jenkins pipeline. Error handling leans on github.com/pingcap/errors and github.com/cockroachdb/errors for wrapped, traceable errors rather than bare error strings, and errno/errctx packages centralize MySQL-compatible error codes.

What Makes It Unique TiDB’s distinguishing technical choice is running true HTAP from one cluster: TiFlash replicates TiKV’s row data into a columnar format in real time over a Multi-Raft Learner protocol, and the same optimizer decides per-query whether to route work to the row store or the columnar replicas — most competing distributed SQL databases require a separate analytical system fed by batch ETL. Combined with a two-phase-commit-over-Raft transaction model adapted from Google’s Percolator paper and full MySQL wire-protocol compatibility, it lets teams get horizontally scalable, strongly consistent OLTP and real-time analytics without changing client tooling or maintaining a parallel data pipeline.