Getting started

This page covers building TiDB from source in this repository, running it locally, and pointing the resulting binary at storage. It is aimed at contributors. End users running TiDB in production should follow the official deployment docs at https://docs.pingcap.com/tidb/stable.

Prerequisites

• Go: the toolchain version is pinned in go.mod (go 1.25.9 at the time of this snapshot). Check the file before installing.
• Make, git, a C toolchain (for some CGO dependencies). On macOS, CGO is required for the gosigar package — see the CGO_ENABLED_FOR_LINT switch in Makefile.
• Bazel (optional but recommended for large-scale work). The repo uses Bazel via WORKSPACE/MODULE.bazel. The version is pinned in .bazelversion.
• TiUP (recommended). For running a local cluster (TiDB + TiKV + PD), install TiUP from https://tiup.io. The repo's testing flow expects tiup playground for realtikvtest and Lightning/BR integration tests.
• MySQL client for connecting to a running TiDB.

Building

The default make target builds tidb-server:

make
# or explicitly
make server

The output binary is written to bin/tidb-server. Other useful targets, defined in Makefile:

Target	What it builds
make server	TiDB SQL server (bin/tidb-server)
make server_debug	TiDB server with debug symbols
make server_check	TiDB server with extra admin checks enabled
make build_br	BR backup/restore CLI (bin/br)
make build_lightning	TiDB Lightning importer (bin/tidb-lightning)
make build_lightning-ctl	Lightning control CLI (bin/tidb-lightning-ctl)
make build_dumpling	Dumpling logical exporter (bin/dumpling)
make build_tools	Repository helper tools (tools/...)
make parser	Regenerate the parser from pkg/parser/parser.y
make bazel_bin	Build the server with Bazel (used in CI)

Running TiDB locally

Option A: against a real TiKV cluster (recommended)

The fastest way to get a working cluster is TiUP Playground:

tiup playground
# or with explicit topology
tiup playground --db 1 --pd 1 --kv 1

This starts TiKV, PD, and a TiDB server on 127.0.0.1:4000. Connect with any MySQL client:

mysql -h 127.0.0.1 -P 4000 -u root

To run the freshly built TiDB binary against TiUP's TiKV/PD, stop only the playground's TiDB component and run your binary with:

./bin/tidb-server --store=tikv --path=127.0.0.1:2379

--store=tikv selects the production driver in pkg/store/driver/tikv_driver.go; --path lists PD endpoints.

Option B: in-memory mocked store

For experimentation without TiKV/PD, TiDB can run against an embedded mock store backed by pkg/store/mockstore/:

./bin/tidb-server --store=unistore --path=""

This is the default mode that many unit tests use (pkg/testkit/ builds clusters on top of unistore). It is not suitable for production but is fine for SQL-level experimentation.

Running tests

The project uses both standard Go tests and a Bazel-driven CI pipeline. The full policy lives in AGENTS.md (root) and docs/agents/testing-flow.md. The minimum daily commands:

Goal	Command
Run a single unit test	go test -run TestX -tags=intest,deadlock ./pkg/<pkg>/...
Run failpoint-using tests	./tools/check/failpoint-go-test.sh pkg/<pkg> -run TestX
Run the integration test suite	pushd tests/integrationtest && ./run-tests.sh -r <name> && popd
Run real-TiKV tests	start tiup playground --mode tikv-slim --tag realtikvtest, then go test -tags=intest,deadlock ./tests/realtikvtest/<dir>/...
Bazel CI run	make bazel_test
Lint changed code	make lint (also bazel_lint_changed in CI; do not run locally without need)
Format Go code	make fmt

See Testing for more detail and docs/agents/testing-flow.md for the canonical command sets, including failpoint enable/disable rules and integration test recording flows.

Configuration

TiDB reads its configuration from a TOML file passed via --config <path>. A documented example is bundled at pkg/config/config.toml.example. Configuration parsing and defaults live in pkg/config/config.go. Connection-time system variables and session settings come from pkg/sessionctx/variable/sysvar.go.

The HTTP status server (default :10080) exposes runtime introspection — /debug/pprof, Prometheus metrics, slow query info, schema dumps, and DDL job status. The full HTTP API is documented in docs/tidb_http_api.md.

Where to go next

• Architecture — how the server is wired together.
• Patterns and conventions — coding style and conventions enforced by the repo.
• Testing — how to run and write tests.
• The repo's AGENTS.md (root) and docs/agents/ directory — formal contributor and agent runbooks.