# TiDB — Distributed SQL Database with MySQL Compatibility

> TiDB is an open-source, cloud-native, distributed SQL database that supports hybrid transactional and analytical processing (HTAP). MySQL-compatible wire protocol, horizontal scalability, strong consistency, and elastic scaling.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Quick start with tiup (TiDB official installer)
curl --proto =https --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
source ~/.zshrc

# Single-instance playground
tiup playground

# Connect via MySQL client
mysql -h 127.0.0.1 -P 4000 -u root
```

Usage (MySQL-compatible SQL):
```sql
CREATE DATABASE tokrepo;
USE tokrepo;

CREATE TABLE users (
  id BIGINT AUTO_RANDOM PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(100),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (email, name) VALUES ("w@tokrepo.com", "William");

SELECT * FROM users WHERE email = "w@tokrepo.com";

-- TiDB-specific: analytical queries use TiFlash columnar replica
ALTER TABLE users SET TIFLASH REPLICA 1;
```

## Intro

TiDB is an open-source, cloud-native, distributed SQL database developed by PingCAP. Combines the scalability of NoSQL with the strong consistency and SQL support of traditional RDBMS. MySQL-compatible wire protocol makes it a drop-in for MySQL apps needing horizontal scale. Supports hybrid transactional/analytical processing (HTAP) via TiFlash columnar engine.

- **Repo**: https://github.com/pingcap/tidb
- **Stars**: 39K+
- **Language**: Go
- **License**: Apache 2.0

## What TiDB Does

- **Distributed SQL** — horizontal scaling like NoSQL but with SQL and ACID
- **MySQL compatible** — wire protocol + most MySQL syntax
- **HTAP** — row-store (TiKV) + column-store (TiFlash) for mixed workloads
- **Raft consensus** — strong consistency across replicas
- **Elastic scale** — add nodes without downtime
- **Online DDL** — schema changes without locks
- **Auto-sharding** — data automatically partitioned and rebalanced
- **Cross-region clusters** — geo-distributed deployments

## Architecture

Three layers:
- **TiDB servers** — stateless SQL layer, parse/plan/execute queries
- **TiKV** — distributed KV store (Rust), uses Raft for replication
- **PD (Placement Driver)** — cluster metadata and scheduling
- **TiFlash** (optional) — columnar replica for analytics

## Self-Hosting

```bash
# Production deployment
tiup cluster deploy mycluster v7.5.0 topology.yaml
tiup cluster start mycluster
tiup cluster display mycluster

# Scale out
tiup cluster scale-out mycluster scale.yaml
```

## Key Features

- MySQL 5.7/8.0 compatibility
- Distributed SQL with ACID
- HTAP (TiFlash columnar)
- Elastic horizontal scaling
- Online DDL
- Point-in-time recovery
- Encryption at rest
- Cloud-ready (TiDB Cloud managed service)
- PingCAP official tools ecosystem

## Comparison

| Database | Model | SQL Standard | Scaling |
|---|---|---|---|
| TiDB | Distributed SQL | MySQL-compatible | Horizontal |
| CockroachDB | Distributed SQL | PostgreSQL-compatible | Horizontal |
| YugabyteDB | Distributed SQL | PostgreSQL-compatible | Horizontal |
| Spanner | Distributed SQL | Managed | Managed |
| Vitess | MySQL sharding | MySQL | Horizontal |
| MySQL Group Replication | HA cluster | MySQL | Vertical + replicas |

## FAQ

**Q: Can it replace MySQL?**
A: Yes in most scenarios, with 95%+ compatibility. But some MySQL features (like event scheduler or specifying storage engines) are not supported. Do a compatibility test before migrating.

**Q: What is TiFlash?**
A: A columnar replica that syncs TiKV data to columnar storage to accelerate analytical queries. A single table can have both row storage (OLTP) and column storage (OLAP).

**Q: Minimum production deployment?**
A: 3 PD + 3 TiKV + 2 TiDB = 8 nodes. TiFlash is optional. TiDB Cloud has a minimum of 3 nodes.

## Sources

- Docs: https://docs.pingcap.com/tidb
- GitHub: https://github.com/pingcap/tidb
- License: Apache 2.0

---
Source: https://tokrepo.com/en/workflows/tidb-distributed-sql-database-mysql-compatibility-90136633
Author: Script Depot