TiDB Local Development Environment

A minimal TiDB instance for local development.

Architecture

┌─────────────────────────────────────────────────┐
│              Your macOS (OrbStack)              │
│                                                 │
│  ┌──────────────┐      ┌──────────────┐        │
│  │   DataGrip   │──────▶│     TiDB     │        │
│  │  (port 4000) │      │  (Standalone) │        │
│  └──────────────┘      └──────────────┘        │
└─────────────────────────────────────────────────┘

Components:

• TiDB (Standalone Mode): Runs with embedded storage (unistore), no separate PD/TiKV needed

Quick Reference

Connection Info

Service	Host	Port	User	Password
TiDB	127.0.0.1	4000	root	(empty)

Useful Commands

``bash

Start environment

./start.sh

Test connection

./test-connection.sh

Connect with MySQL client

mysql -h 127.0.0.1 -P 4000 -u root

View logs

docker compose logs -f

Stop environment

docker compose down

For DataGrip/DBeaver setup, see [DATAGRIP_SETUP.md](DATAGRIP_SETUP.md)

## Prerequisites

- macOS with OrbStack (or Docker Desktop)
- Docker Compose v2 (command: `docker compose`, not `docker-compose`)

**Check your setup:**
```bash
./check-docker.sh

Note: If you have Docker Compose v1 only, see DOCKER_COMPOSE_V2.md for migration options.

Configuration

No configuration needed for the basic setup.

Usage

Start the environment

``bash docker compose up -d

This will:
1. Start TiDB in standalone mode

### Connect to local TiDB

**Command Line:**
```bash
mysql -h 127.0.0.1 -P 4000 -u root

DataGrip / MySQL Workbench / DBeaver:

• Host: 127.0.0.1
• Port: 4000
• User: root
• Password: (leave empty)

See DATAGRIP_SETUP.md for detailed client setup instructions.

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f tidb

Stop the environment

``bash docker compose down

### Reset everything (including data)
```bash
docker compose down -v

Troubleshooting

TiDB connection issues

• Verify TiDB is running: docker ps | grep tidb
• Check health: docker exec tidb mysql -h 127.0.0.1 -P 4000 -u root -e "SELECT 1"

Resource Usage

Default resource limits (suitable for local development):

• TiDB: 2 CPU, 2GB RAM

Adjust in docker-compose.yml if needed.

Notes

• Docker Compose v2: This project uses docker compose (v2 syntax). If you have v1, either upgrade or create an alias: alias docker-compose='docker compose'
• Standalone Mode: TiDB runs without distributed storage, suitable for development only
• Data Persistence: Data is stored in Docker volumes, persists across restarts