# TiDB Cluster

> Distributed NewSQL database compatible with MySQL protocol.

- Category: Database Stacks
- Difficulty: advanced
- Components: tidb, tikv, pd
- Tags: tidb, distributed, mysql-compatible, newsql, htap
- Source: https://docker.recipes/databases/tidb

## Overview

TiDB is a distributed NewSQL database designed by PingCAP that combines the scalability of NoSQL systems with the ACID guarantees and SQL compatibility of traditional relational databases. Originally developed to address the limitations of MySQL in handling massive datasets and high concurrency, TiDB implements the Raft consensus algorithm for data consistency and supports horizontal scaling across commodity hardware. The database architecture separates compute and storage layers, enabling independent scaling of processing power and storage capacity while maintaining MySQL wire protocol compatibility.

This stack deploys a complete TiDB cluster consisting of three essential components that work in concert to deliver distributed database capabilities. PD (Placement Driver) serves as the cluster metadata manager and timestamp oracle, coordinating data placement decisions and maintaining cluster topology information. TiKV acts as the distributed key-value storage engine, storing actual data across multiple nodes with automatic sharding and replication. TiDB functions as the SQL layer, parsing queries, generating execution plans, and coordinating with TiKV nodes to retrieve and manipulate data.

Developers building applications that outgrow single-instance MySQL deployments will find this configuration particularly valuable, as it provides MySQL compatibility while enabling petabyte-scale storage and handling millions of concurrent connections. The HTAP (Hybrid Transactional/Analytical Processing) capabilities make it ideal for organizations needing real-time analytics on operational data without maintaining separate OLTP and OLAP systems. Enterprises dealing with rapid data growth, gaming companies managing player statistics, financial services requiring high availability, and SaaS platforms needing multi-tenant database solutions benefit from TiDB's horizontal scaling and strong consistency guarantees.

## Features

- MySQL 5.7 protocol compatibility enabling drop-in replacement for existing MySQL applications
- HTAP architecture supporting both OLTP workloads and real-time analytical queries on the same dataset
- Automatic horizontal sharding with configurable replica count for fault tolerance
- Multi-version concurrency control (MVCC) with snapshot isolation for consistent reads
- Raft consensus algorithm ensuring strong consistency across distributed storage nodes
- Online DDL operations allowing schema changes without downtime or table locks
- Cross-data center replication with configurable placement rules for compliance requirements
- Built-in distributed transaction support with two-phase commit protocol

## Use cases

- Scaling existing MySQL applications beyond single-server limitations while maintaining compatibility
- Building multi-tenant SaaS platforms requiring isolated data with consistent performance
- Real-time analytics dashboards that need fresh data without impacting transactional workloads
- Gaming backend systems managing player profiles, leaderboards, and transaction histories
- Financial applications requiring ACID compliance with high availability and disaster recovery
- E-commerce platforms handling inventory management and real-time recommendation engines
- IoT data ingestion systems processing time-series data with complex analytical queries

## Prerequisites

- Minimum 8GB RAM available (2GB for TiDB, 4GB for TiKV, 1GB for PD components)
- Docker Engine 20.10+ with BuildKit support for multi-stage builds
- Available ports 2379 (PD client), 4000 (TiDB SQL), and 10080 (TiDB status API)
- Basic understanding of distributed systems concepts and MySQL query syntax
- SSD storage recommended for TiKV data directory to ensure optimal write performance
- Network connectivity allowing inter-container communication on custom bridge networks

## docker-compose.yml

```yaml
services:
  pd:
    image: pingcap/pd:latest
    container_name: pd
    command: --name=pd --client-urls=http://0.0.0.0:2379 --peer-urls=http://0.0.0.0:2380 --data-dir=/data
    volumes:
      - pd_data:/data
    ports:
      - "2379:2379"
    networks:
      - tidb-network

  tikv:
    image: pingcap/tikv:latest
    container_name: tikv
    command: --addr=0.0.0.0:20160 --advertise-addr=tikv:20160 --pd=pd:2379 --data-dir=/data
    volumes:
      - tikv_data:/data
    depends_on:
      - pd
    networks:
      - tidb-network

  tidb:
    image: pingcap/tidb:latest
    container_name: tidb
    command: --store=tikv --path=pd:2379
    ports:
      - "4000:4000"
      - "10080:10080"
    depends_on:
      - tikv
    networks:
      - tidb-network

volumes:
  pd_data:
  tikv_data:

networks:
  tidb-network:
    driver: bridge
```

## .env

```bash
# TiDB default configuration
# Connect using MySQL client on port 4000
```

## Usage notes

- Docs: https://docs.pingcap.com/tidb/stable
- MySQL-compatible on port 4000 - use mysql client
- Status API at http://localhost:10080/status
- Connect: mysql -h 127.0.0.1 -P 4000 -u root
- HTAP: combine transactional and analytical workloads
- Horizontal scaling - add TiKV nodes for storage capacity

## Troubleshooting

- TiKV fails to start with 'failed to get cluster id': Ensure PD container is fully started before TiKV initialization
- Connection refused on port 4000: Verify TiKV has successfully registered with PD before TiDB starts accepting connections
- PD panic with 'etcd cluster ID mismatch': Remove pd_data volume and restart cluster to reinitialize metadata
- TiDB reports 'PD server timeout': Check PD container logs for clock synchronization issues between containers
- Slow query performance: Monitor TiKV memory usage and consider increasing container memory limits above 4GB
- Schema changes hanging indefinitely: Check for long-running transactions that may block DDL operations

