# pingcap/tidb architecture

> Architecture diagram of the GitHub repository pingcap/tidb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pingcap/tidb
- Repository: https://github.com/pingcap/tidb

## Overview

TiDB is a distributed SQL database: applications submit SQL to a server, which compiles and executes queries using distributed storage and cluster services. The tree also contains major data-movement products: Dumpling exports data, Lightning imports it, and BR backs up and restores clusters; BR’s stream commands support log-based recovery workflows. The graph follows documented architecture and sampled source where available. Several subsystem connections are documented or indicated by the tree rather than verified from unsampled call sites.

Main entry points: [`br/cmd/br/cmd.go`](https://github.com/pingcap/tidb/blob/master/br/cmd/br/cmd.go) (BR commands), [`cmd/tidb-server/main.go`](https://github.com/pingcap/tidb/blob/master/cmd/tidb-server/main.go) (TiDB server), [`pkg/executor/builder.go`](https://github.com/pingcap/tidb/blob/master/pkg/executor/builder.go) (Query executors), [`pkg/distsql/distsql.go`](https://github.com/pingcap/tidb/blob/master/pkg/distsql/distsql.go) (Distributed SQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["SQL serving"]
  node_tidb["TiDB server<br/>[main.go]"]
  node_compiler["SQL compiler<br/>[compiler.go]"]
end

subgraph group_execution["Query execution"]
  node_executor["Query executors<br/>[builder.go]"]
  node_windows["Window execution"]
  node_distsql["Distributed SQL<br/>[distsql.go]"]
end

subgraph group_cluster["Cluster services"]
  node_domain["Domain services<br/>[domain.go]"]
  node_ddl["Schema management<br/>[ddl.go]"]
  node_transition["Storage transitions"]
end

subgraph group_migration["Data movement"]
  node_dumpling["Dumpling exporter<br/>[dump.go]"]
  node_lightning["Lightning importer<br/>[import.go]"]
  node_lightning_server["Import service<br/>[lightning.go]"]
end

subgraph group_recovery["Backup and recovery"]
  node_br["BR commands<br/>[cmd.go]"]
  node_backup["Backup tasks<br/>[backup.go]"]
  node_restore["Restore tasks<br/>[restore.go]"]
  node_stream["Log stream<br/>[stream.go]"]
end

node_applications(("SQL clients"))
node_pd["Placement Director"]
node_tikv[("TiKV row store")]
node_tiflash[("TiFlash column store")]
node_object_storage[("Object storage<br/>[storage.go]")]
node_mysql(("MySQL-compatible apps"))

node_applications -->|"send SQL"| node_tidb
node_tidb -->|"compile queries"| node_compiler
node_compiler -->|"build execution"| node_executor
node_executor -->|"run operators"| node_windows
node_executor -->|"dispatch requests"| node_distsql
node_distsql -->|"send requests"| node_tikv
node_distsql -.->|"send requests"| node_tiflash
node_tidb -->|"use services"| node_domain
node_domain -->|"manage schema"| node_ddl
node_ddl -->|"coordinate placement"| node_pd
node_transition -->|"observe replicas"| node_tiflash
node_dumpling -->|"read SQL data"| node_mysql
node_lightning_server -->|"run imports"| node_lightning
node_lightning -->|"import data"| node_tikv
node_br -->|"dispatch backup"| node_backup
node_br -->|"dispatch restore"| node_restore
node_br -->|"dispatch stream"| node_stream
node_backup -->|"read data"| node_tikv
node_backup -->|"write backup"| node_object_storage
node_restore -->|"read backup"| node_object_storage
node_restore -->|"restore data"| node_tikv
node_stream -->|"store stream data"| node_object_storage

click node_tidb "https://github.com/pingcap/tidb/blob/master/cmd/tidb-server/main.go"
click node_compiler "https://github.com/pingcap/tidb/blob/master/pkg/executor/compiler.go"
click node_executor "https://github.com/pingcap/tidb/blob/master/pkg/executor/builder.go"
click node_windows "https://github.com/pingcap/tidb/blob/master/pkg/executor/windows/pipelined_window.go"
click node_distsql "https://github.com/pingcap/tidb/blob/master/pkg/distsql/distsql.go"
click node_domain "https://github.com/pingcap/tidb/blob/master/pkg/domain/domain.go"
click node_ddl "https://github.com/pingcap/tidb/blob/master/pkg/ddl/ddl.go"
click node_transition "https://github.com/pingcap/tidb/blob/master/pkg/ddl/storage_class_transition.go"
click node_dumpling "https://github.com/pingcap/tidb/blob/master/dumpling/export/dump.go"
click node_lightning "https://github.com/pingcap/tidb/blob/master/lightning/pkg/importer/import.go"
click node_lightning_server "https://github.com/pingcap/tidb/blob/master/lightning/pkg/server/lightning.go"
click node_br "https://github.com/pingcap/tidb/blob/master/br/cmd/br/cmd.go"
click node_backup "https://github.com/pingcap/tidb/blob/master/br/pkg/task/backup.go"
click node_restore "https://github.com/pingcap/tidb/blob/master/br/pkg/task/restore.go"
click node_stream "https://github.com/pingcap/tidb/blob/master/br/pkg/task/stream.go"
click node_object_storage "https://github.com/pingcap/tidb/blob/master/pkg/objstore/storage.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tidb,node_compiler,node_applications toneBlue
class node_executor,node_windows,node_distsql,node_tikv,node_tiflash,node_object_storage toneAmber
class node_domain,node_ddl,node_transition toneMint
class node_dumpling,node_lightning,node_lightning_server toneRose
class node_br,node_backup,node_restore,node_stream,node_pd,node_mysql toneIndigo
```

## Components

### SQL serving

- [TiDB server](https://github.com/pingcap/tidb/blob/master/cmd/tidb-server/main.go): `cmd/tidb-server/main.go`
- [SQL compiler](https://github.com/pingcap/tidb/blob/master/pkg/executor/compiler.go): `pkg/executor/compiler.go`

### Query execution

- [Query executors](https://github.com/pingcap/tidb/blob/master/pkg/executor/builder.go): `pkg/executor/builder.go`
- [Window execution](https://github.com/pingcap/tidb/blob/master/pkg/executor/windows/pipelined_window.go): `pkg/executor/windows/pipelined_window.go`
- [Distributed SQL](https://github.com/pingcap/tidb/blob/master/pkg/distsql/distsql.go): `pkg/distsql/distsql.go`

### Cluster services

- [Domain services](https://github.com/pingcap/tidb/blob/master/pkg/domain/domain.go): `pkg/domain/domain.go`
- [Schema management](https://github.com/pingcap/tidb/blob/master/pkg/ddl/ddl.go): `pkg/ddl/ddl.go`
- [Storage transitions](https://github.com/pingcap/tidb/blob/master/pkg/ddl/storage_class_transition.go): `pkg/ddl/storage_class_transition.go`

### Data movement

- [Dumpling exporter](https://github.com/pingcap/tidb/blob/master/dumpling/export/dump.go): `dumpling/export/dump.go`
- [Lightning importer](https://github.com/pingcap/tidb/blob/master/lightning/pkg/importer/import.go): `lightning/pkg/importer/import.go`
- [Import service](https://github.com/pingcap/tidb/blob/master/lightning/pkg/server/lightning.go): `lightning/pkg/server/lightning.go`

### Backup and recovery

- [BR commands](https://github.com/pingcap/tidb/blob/master/br/cmd/br/cmd.go): `br/cmd/br/cmd.go`
- [Backup tasks](https://github.com/pingcap/tidb/blob/master/br/pkg/task/backup.go): `br/pkg/task/backup.go`
- [Restore tasks](https://github.com/pingcap/tidb/blob/master/br/pkg/task/restore.go): `br/pkg/task/restore.go`
- [Log stream](https://github.com/pingcap/tidb/blob/master/br/pkg/task/stream.go): `br/pkg/task/stream.go`

### Other components

- **SQL clients**
- **Placement Director**
- **TiKV row store**
- **TiFlash column store**
- [Object storage](https://github.com/pingcap/tidb/blob/master/pkg/objstore/storage.go): `pkg/objstore/storage.go`
- **MySQL-compatible apps**

## Connections

- SQL clients → TiDB server: send SQL
- TiDB server → SQL compiler: compile queries
- SQL compiler → Query executors: build execution
- Query executors → Window execution: run operators
- Query executors → Distributed SQL: dispatch requests
- Distributed SQL → TiKV row store: send requests
- Distributed SQL → TiFlash column store: send requests
- TiDB server → Domain services: use services
- Domain services → Schema management: manage schema
- Schema management → Placement Director: coordinate placement
- Storage transitions → TiFlash column store: observe replicas
- Dumpling exporter → MySQL-compatible apps: read SQL data
- Import service → Lightning importer: run imports
- Lightning importer → TiKV row store: import data
- BR commands → Backup tasks: dispatch backup
- BR commands → Restore tasks: dispatch restore
- BR commands → Log stream: dispatch stream
- Backup tasks → TiKV row store: read data
- Backup tasks → Object storage: write backup
- Restore tasks → Object storage: read backup
- Restore tasks → TiKV row store: restore data
- Log stream → Object storage: store stream data