Local Deployment

You can run TiDB locally using three methods. TiUP Playground is the recommended approach because it manages the full cluster lifecycle automatically. Docker is the fastest way to get a single-node instance running. Building from source gives you the most control and is suitable if you are contributing to TiDB.

TiUP Playground (recommended)
Docker
Build from source

TiUP is TiDB’s official component manager. The tiup playground command starts a complete local TiDB cluster including TiDB, TiKV, and PD with a single command.

Install TiUP

Run the TiUP installer script:

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

After installation, reload your shell profile so the tiup binary is on your PATH:

source ~/.bashrc
# or on macOS
source ~/.zshrc

Start the playground cluster

Launch a local TiDB cluster:

tiup playground

TiUP downloads the required components on first run, then starts TiDB on port 4000 and the status API on port 10080. The output shows the connection details once the cluster is ready.To pin a specific TiDB version:

tiup playground v8.1.0

Add --db 2 or --kv 3 flags to start multiple TiDB or TiKV instances for a more realistic multi-node setup.

Connect to TiDB

Open a new terminal and connect using any MySQL-compatible client:

mysql -h 127.0.0.1 -P 4000 -u root

No password is set by default on a fresh playground cluster.

Verify the cluster is running

Check the status endpoint:

curl http://127.0.0.1:10080/status

A healthy response looks like:

{
  "connections": 0,
  "version": "8.x.x",
  "git_hash": "...",
  "status": "ok"
}

Run a single TiDB server node using the official Docker image. This starts TiDB with the built-in unistore storage engine — suitable for development and testing but not for production workloads that require TiKV.

Pull and run the TiDB image

docker run -d \
  --name tidb-server \
  -p 4000:4000 \
  -p 10080:10080 \
  pingcap/tidb

TiDB listens on port 4000 for MySQL connections and port 10080 for the status HTTP API.

Connect to TiDB

mysql -h 127.0.0.1 -P 4000 -u root

Verify the instance is healthy

curl http://127.0.0.1:10080/status

Mount a custom configuration (optional)

To supply your own tidb.toml configuration file:

docker run -d \
  --name tidb-server \
  -p 4000:4000 \
  -p 10080:10080 \
  -v /path/to/tidb.toml:/tidb.toml \
  pingcap/tidb \
  --config=/tidb.toml

See the Configuration Reference for available options.

The pingcap/tidb Docker image uses unistore as its storage engine by default. This is an in-process store intended for testing. For a full distributed cluster with TiKV, use TiUP Playground or TiDB Operator on Kubernetes.

Build the tidb-server binary directly from the source repository. You need Go installed to compile TiDB.

Install prerequisites

Install Go 1.21 or later from go.dev/dl. Verify the installation:

go version

Install make and git if they are not already available on your system.

Clone the repository

git clone https://github.com/pingcap/tidb.git
cd tidb

Build the server binary

make server

This compiles tidb-server and places it at ./bin/tidb-server.

Run tidb-server

Start TiDB with the default in-process unistore storage engine:

./bin/tidb-server

To use a custom configuration file:

./bin/tidb-server --config=/path/to/tidb.toml

Key flags you can pass directly on the command line:

Flag	Default	Description
`--host`	`0.0.0.0`	Address to bind for MySQL connections
`--port`	`4000`	Port for MySQL connections
`--store`	`unistore`	Storage engine (`tikv` or `unistore`)
`--path`	`/tmp/tidb`	Data directory for `unistore`
`--status`	`10080`	Port for the HTTP status API
`--config`	—	Path to a TOML configuration file

Command-line flags override values in the configuration file.

Connect to TiDB

mysql -h 127.0.0.1 -P 4000 -u root

Verify the server is running

curl http://127.0.0.1:10080/status

Testing the connection

Once TiDB is running by any of the methods above, confirm the connection with a basic SQL query:

SELECT tidb_version()\G

This returns the full TiDB version string, including the Git commit hash and build information.

Status API endpoints

The HTTP status API on port 10080 exposes several useful endpoints:

Endpoint	Description
`GET /status`	Server health, version, and connection count
`GET /metrics`	Prometheus metrics
`GET /debug/pprof`	Go pprof profiling data

# Health check
curl http://127.0.0.1:10080/status

# Prometheus metrics
curl http://127.0.0.1:10080/metrics

Next steps

Configuration Reference

Learn how to configure TiDB using a TOML file, including server settings, storage, logging, security, and performance tuning.

Kubernetes Deployment

Deploy a production-grade TiDB cluster on Kubernetes using TiDB Operator.

Get Started

Core Concepts

Deployment

Data Management

Operations

Local Deployment

Testing the connection

Status API endpoints

Next steps

Configuration Reference

Kubernetes Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Data Management

Operations

Documentation Index

​Testing the connection

​Status API endpoints

​Next steps

Configuration Reference

Kubernetes Deployment

Build docs developers (and LLMs) love

Testing the connection

Status API endpoints

Next steps