Systems

This section documents the major internal subsystems of the TiDB server (everything under pkg/). Each subsystem has its own page with the file map, key abstractions, data flow, and integration points.

The grouping mirrors the repository's own subsystem map at docs/agents/architecture-index.md.

Subsystem index

Subsystem	Path	Page
Parser and AST	pkg/parser/	Parser
Planner and optimizer	pkg/planner/	Planner
Executor	pkg/executor/	Executor
Expression engine	pkg/expression/	Expression
Session and transactions	pkg/session/, pkg/sessionctx/, pkg/sessiontxn/	Session
MySQL protocol server	pkg/server/	Server
DDL framework	pkg/ddl/	DDL
Schema cache and metadata	pkg/infoschema/, pkg/meta/	Infoschema and meta
Domain (instance lifecycle)	pkg/domain/	Domain
Storage client and KV	pkg/kv/, pkg/store/, pkg/distsql/, pkg/tablecodec/	Storage
Statistics	pkg/statistics/	Statistics

Other notable subsystems

These don't have a dedicated page in this wiki yet; pointers to read directly:

• Bind info (pkg/bindinfo/) — SQL plan baselines and bindings.
• Plan replayer (pkg/domain/plan_replayer.go) — bundle a query plan for offline analysis.
• DXF — Distributed eXecution Framework (pkg/dxf/) — task framework for distributed ADD INDEX, IMPORT INTO, and big stats jobs.
• Resource control (pkg/resourcegroup/, pkg/resourcemanager/) — RU-based isolation between workloads.
• TTL (pkg/ttl/) — TTL job scheduler that deletes expired rows.
• Lightning library (pkg/lightning/) — physical/logical import backends used by lightning/ CLI and BR.
• Auto-ID service (pkg/autoid_service/) — centralized auto-increment ID allocation.
• Plugin (pkg/plugin/, pkg/extension/) — plugin and extension hooks.
• Privilege (pkg/privilege/) — privilege checks and mysql.user/mysql.db evaluation.
• Workload learning / repository (pkg/workloadlearning/, pkg/util/workloadrepo/) — workload analysis and storage.
• TopSQL (pkg/util/topsql/) — Top-SQL tracing.
• Telemetry (pkg/telemetry/) — telemetry collection (largely deprecated; kept for compatibility).

For directories not listed here, treat the directory name as authoritative — most package names map directly to a feature or capability and contain a doc.go or top-level comment that explains scope. The repo's policy in AGENTS.md is that contributors read doc.go first when entering a new package.

How subsystems connect

The shortest path through the system, with the package responsibility called out:

graph LR
  server[pkg/server<br/>MySQL protocol]
  session[pkg/session<br/>txn lifecycle]
  parser[pkg/parser<br/>SQL → AST]
  planner[pkg/planner<br/>AST → plan]
  executor[pkg/executor<br/>plan → chunks]
  expr[pkg/expression<br/>row eval]
  domain[pkg/domain<br/>schema + stats cache]
  info[pkg/infoschema]
  ddl[pkg/ddl]
  meta[pkg/meta]
  stats[pkg/statistics]
  store[pkg/store + pkg/kv + pkg/distsql]

  server --> session
  session --> parser
  parser --> planner
  planner --> info
  planner --> stats
  planner --> executor
  executor --> expr
  executor --> store
  domain --> info
  domain --> stats
  ddl --> meta
  ddl --> info
  domain -.->|owns| ddl

Read the linked pages in this section for the inside view of each box.