Mark
#1
TiDB by PingCAP is an open-source, distributed SQL database that’s MySQL-compatible and built for scalability. It’s designed for applications that need horizontal scaling, high availability, and hybrid transactional and analytical processing (HTAP).
If you want to try TiDB locally for development or testing, the fastest and easiest method is to use Docker. With Docker, you can spin up a lightweight TiDB cluster on your local machine—without installing everything manually.
In this article, you’ll learn how to install TiDB using Docker, set up a simple standalone cluster, and access the database from your CLI or database tools.

Why Use Docker for TiDB?

Using Docker to run TiDB gives you several benefits:
  • No complex system installation required
  • Quick to start and stop
  • Great for local development and testing
  • Runs consistently across platforms
  • Easy to remove when no longer needed

Prerequisites

Before we begin, make sure you have Docker installed.

For Windows/macOS:

Download Docker Desktop from:
👉 https://www.docker.com/products/docker-desktop

For Ubuntu/Linux:

sudo apt update && sudo apt install docker.io
Verify Docker is working: 
docker --version

Step 1: Pull the TiDB Docker Compose Repository

TiDB typically runs as a cluster of services (TiDB, PD, TiKV), so the easiest way to run it is by using Docker Compose with a pre-built configuration from PingCAP.
Clone the official TiDB Docker Compose setup: 
git clone https://github.com/pingcap/tidb-docker-compose.git && cd tidb-docker-compose
This repo includes a working docker-compose.yml file with all components.

Step 2: Start the TiDB Cluster

Once inside the tidb-docker-compose folder, simply run: 
docker-compose up -d
This command will:
  • Download necessary TiDB, PD, and TiKV images
  • Launch a single-node cluster in detached mode
You can check the running containers with: 
docker ps
You should see containers for:
  • pd: Placement Driver (cluster metadata manager)
  • tikv: Distributed key-value storage engine
  • tidb: SQL layer (MySQL-compatible interface)

Step 3: Connect to TiDB

TiDB uses the standard MySQL protocol, so you can connect using any MySQL client or GUI.

Connect using MySQL CLI:

If you have MySQL installed on your host machine: 
mysql -h 127.0.0.1 -P 4000 -u root
Port 4000 is the default SQL port used by TiDB.

Connect using GUI (e.g., DBeaver, DataGrip, MySQL Workbench)

Connection settings:
  • Host: 127.0.0.1
  • Port: 4000
  • User: root
  • Password: (leave blank, or use an empty password)
Once connected, you can run standard SQL queries just like with MySQL.

Step 4: Managing the Cluster

Here are a few useful Docker commands:
Task Command
Stop the cluster docker-compose down
Restart the cluster docker-compose up -d
View logs docker-compose logs -f tidb
Remove all containers docker-compose down -v

Step 5: Run Sample SQL

Once connected, you can start using TiDB like a regular SQL database. 
CREATE DATABASE testdb;

USE testdb;

CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  name VARCHAR(100),
  email VARCHAR(100)
);

INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

SELECT * FROM users;
You’ll see results returned, confirming that your TiDB instance is working properly.

Optional: Persist Data

The default docker-compose.yml setup uses Docker volumes to persist TiKV storage. You don’t need to change anything to keep your data between restarts.
If you want to reset the cluster and start fresh, simply run: 
docker-compose down -v
This deletes all data volumes used by TiKV.

Best Practices

  • Use TiDB only in standalone mode for development via Docker (not for production)
  • Always stop the cluster with docker-compose down to avoid data corruption
  • Use port 4000 for MySQL-compatible connections
  • Don’t forget to pull the latest images before restarting the cluster

image quote pre code
Share: