# 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](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](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