第一章：TiDB 概述与核心特性
1.1 什么是 TiDB
| 概念名称 | 说明 | 注意事项 |
|---|
| TiDB 定义 | TiDB 是一款开源的分布式关系型数据库，支持水平弹性扩展、强一致性事务、实时 HTAP（混合事务/分析处理）能力，兼容 MySQL 协议。 | TiDB 不是 MySQL 的分支，而是全新实现的分布式数据库，仅协议和语法兼容。 |
| 开源属性 | 由 PingCAP 公司主导开发，采用 Apache 2.0 许可证开源。 | 社区版功能完整，企业版提供额外运维工具和商业支持。 |
| 核心目标 | 解决传统单机数据库在高并发、大数据量场景下的扩展性瓶颈，同时保持 SQL 易用性和 ACID 事务能力。 | 不适用于对存储过程、触发器等高级 MySQL 特性强依赖的遗留系统。 |
1.2 TiDB 架构组成
| 组件名称 | 说明 | 注意事项 |
|---|
| TiDB Server | 无状态的 SQL 层，负责 SQL 解析、查询优化、执行计划生成，兼容 MySQL 协议。 | 本身不存储数据，需连接 PD 和 TiKV；可水平扩展以提升吞吐。 |
| PD（Placement Driver） | 集群的元数据管理与调度中心，负责时间戳分配、Region 路由信息维护、负载均衡调度。 | 必须部署奇数个节点（通常 3 或 5）以保证 Raft 一致性；是集群的”大脑”。 |
| TiKV | 分布式 KV 存储引擎，基于 Raft 协议实现多副本强一致性，底层使用 RocksDB。 | 数据实际存储位置；Region 是其最小调度单位（默认 96MB）。 |
| TiFlash（可选） | 列式存储引擎，用于 HTAP 场景，通过异步复制从 TiKV 同步数据，支持实时分析查询。 | 需显式指定使用（如 SELECT /*+ READ_FROM_STORAGE(TIFLASH[t]) */）；增加硬件成本。 |
| CDC / Dumpling / Lightning 等工具 | 生态工具，分别用于变更数据捕获、逻辑备份导出、高速数据导入。 | 不属于核心运行组件，但对生产环境至关重要。 |
1.3 TiDB 与 MySQL 兼容性说明
| 兼容项 | 说明 | 注意事项 |
|---|
| 协议兼容 | 支持 MySQL 5.7 协议，绝大多数 MySQL 客户端（如 mysql CLI、JDBC、Navicat）可直接连接。 | 不支持 COM_STMT_SEND_LONG_DATA 等少数协议命令。 |
| DDL 语法 | 支持 CREATE/DROP/ALTER TABLE、INDEX 等常用 DDL，且在线 DDL 不阻塞读写。 | 不支持 FOREIGN KEY 约束（解析通过但不生效）；部分 ALTER 操作有限制。 |
| DML 与查询 | 支持标准 SELECT/INSERT/UPDATE/DELETE，JOIN、子查询、窗口函数（v4.0+）等。 | 不支持 SELECT ... FOR UPDATE SKIP LOCKED/NOWAIT；部分函数缺失（如 GET_LOCK）。 |
| 数据类型 | 支持 INT、VARCHAR、DATETIME、JSON（v3.1+）、DECIMAL 等主流类型。 | 不支持 GEOMETRY、ENUM、SET 等 MySQL 特有类型。 |
| 事务模型 | 支持 ACID 事务，默认使用乐观事务（v3.0+），也支持悲观事务模式。 | 乐观事务在高冲突场景下可能频繁重试；需应用层处理 retryable error。 |
1.4 TiDB 适用场景与优势
| 场景/优势类别 | 说明 | 注意事项 |
|---|
| 高并发 OLTP | 支持每秒数十万级 QPS，通过水平扩展 TiDB/TiKV 节点线性提升吞吐。 | 写入热点（如单调递增主键）可能导致性能瓶颈，需合理设计分片键。 |
| 实时 HTAP | 通过 TiFlash 实现同一份数据的实时分析，避免 ETL 延迟。 | 分析查询需显式路由到 TiFlash，或通过 CBO 自动选择（需统计信息准确）。 |
| 弹性扩展 | 在线扩缩容，无需停机，自动 rebalance 数据。 | 扩容后需等待 Region 调度完成才能发挥全部性能；缩容需确保副本安全。 |
| 云原生友好 | 支持 Kubernetes 部署（TiDB Operator），适配公有云/混合云架构。 | 对网络延迟敏感，跨 AZ 部署需评估性能影响。 |
| 高可用与灾备 | 多副本 + Raft 协议保障数据不丢失，支持跨数据中心部署（PD Placement Rules）。 | 异地多活需配合应用层设计；RPO≈0，RTO<30s（典型场景）。 |
第二章：TiDB 安装与部署
2.1 单机快速部署（TiUP playground）
| 操作名称 | 操作细节 | 注意事项 |
|---|
| 安装 TiUP | 执行 curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh 安装 TiUP 工具。 | 需确保系统已安装 curl、bash；安装后需执行 source ~/.bashrc 或重新登录生效。 |
| 启动 playground | 执行 tiup playground 启动包含 TiDB、TiKV、PD、TiFlash 的本地测试集群。 | 默认启动最新稳定版；首次运行会自动下载组件，需联网。 |
| 指定版本启动 | 执行 tiup playground v7.5.0 启动指定版本集群。 | 版本号需存在于 TiUP 镜像中；可通过 tiup list tidb 查看可用版本。 |
| 自定义组件数量 | 执行 tiup playground --db 2 --kv 3 --pd 3 --tiflash 1 指定各组件实例数。 | 仅用于测试；生产环境不推荐在单机运行多副本。 |
| 连接数据库 | 使用 mysql -u root -h 127.0.0.1 -P 4000 连接 TiDB 服务。 | 默认无密码；端口 4000 为 TiDB SQL 服务端口。 |
2.2 生产环境部署（TiUP cluster）
| 操作名称 | 操作细节 | 注意事项 |
|---|
| 初始化 TiUP | 执行 tiup cluster 首次使用时自动初始化；或手动 tiup install cluster。 | 确保 tiup 版本 ≥ v1.3；建议使用最新 LTS 版本。 |
| 编写拓扑配置文件 | 创建 YAML 文件（如 topology.yaml），定义 PD、TiDB、TiKV、TiFlash、Monitoring 等节点 IP 与端口。 | 必须为不同组件分配独立机器；避免单点故障；PD 节点数应为奇数。 |
| 检查部署环境 | 执行 tiup cluster check ./topology.yaml --user root -p 检查目标机器环境（磁盘、内存、OS 等）。 | 需目标机器允许 SSH 免密登录；建议使用专用部署用户（非 root）。 |
| 部署集群 | 执行 tiup cluster deploy <cluster-name> v7.5.0 ./topology.yaml --user root -p 部署集群。 | <cluster-name> 为自定义名称；部署过程不可中断。 |
| 启动集群 | 执行 tiup cluster start <cluster-name> 启动已部署集群。 | 首次启动可能较慢（需初始化数据目录）；可通过 tiup cluster display <cluster-name> 查看状态。 |
| 扩容节点 | 编写 scale-out.yaml，执行 tiup cluster scale-out <cluster-name> scale-out.yaml。 | 扩容 TiKV/TiFlash 后需等待 Region 均衡完成才可发挥性能。 |
| 缩容节点 | 执行 tiup cluster scale-in <cluster-name> --node <ip:port> 安全下线节点。 | 缩容前确保数据已迁移；不可直接 kill 进程。 |
2.3 Docker / Kubernetes 部署方式
| 部署方式 | 操作细节 | 注意事项 |
|---|
| Docker Compose 快速启动 | 下载官方 docker-compose.yml，执行 docker-compose up -d 启动单机集群。 | 仅用于开发测试；不支持持久化配置修改；性能受限。 |
| Helm 部署（Kubernetes） | 添加 PingCAP Helm 仓库：helm repo add pingcap https://charts.pingcap.org/；执行 helm install tidb-cluster pingcap/tidb-cluster -n tidb --create-namespace。 | 需提前配置 StorageClass、PV；建议使用 TiDB Operator 管理。 |
| 使用 TiDB Operator | 部署 CRD 和 controller：kubectl apply -f https://github.com/pingcap/tidb-operator/raw/master/manifests/crd.yaml；再部署 TidbCluster 自定义资源。 | Operator 支持自动故障恢复、备份、升级；适合云原生生产环境。 |
| 持久化配置 | 在 Helm values.yaml 或 TidbCluster CR 中指定 storageClassName、resources、config 等。 | 必须配置持久化存储，否则 Pod 重建后数据丢失。 |
| 访问 TiDB 服务 | 通过 Kubernetes Service：kubectl port-forward svc/<cluster-name>-tidb 4000:4000 -n tidb。 | 生产环境应配置 Ingress 或 LoadBalancer 类型 Service。 |
2.4 验证部署状态与服务连通性
| 验证项 | 操作细节 | 注意事项 |
|---|
| 查看集群状态 | 执行 tiup cluster display <cluster-name> 查看各组件运行状态、端口、版本。 | “Up” 表示正常；“Down” 需检查日志（tiup cluster audit 或 /tidb-deploy/*/log）。 |
| 连接 TiDB 服务 | 执行 mysql -u root -h <tidb-ip> -P 4000 -e "SELECT VERSION();" 验证 SQL 连通性。 | 若启用 TLS，需添加 --ssl-mode=REQUIRED；默认无密码。 |
| 检查 PD 健康状态 | 访问 http://<pd-ip>:2379/pd/api/v1/members 或使用 pd-ctl -u http://<pd-ip>:2379 member。 | 返回的 members 应全部处于 “healthy” 状态。 |
| 验证 TiKV 存储 | 执行 tikv-ctl --host <tikv-ip>:20160 store 查看 Store 状态（需安装 tikv-ctl）。 | Store 状态应为 “Up”；Leader Count 应均衡。 |
| 验证监控系统 | 访问 http://<grafana-ip>:3000（默认账号 admin/admin），查看 TiDB Overview 面板。 | 若未部署监控组件（如 prometheus、grafana），该服务不存在。 |
| 测试简单写入 | 执行 CREATE DATABASE test; USE test; CREATE TABLE t(id INT); INSERT INTO t VALUES (1); SELECT * FROM t; | 成功返回结果即表示基本读写功能正常。 |
第三章：TiDB 基础 SQL 操作
3.1 数据库与表的创建与管理
| 方法/语句名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 创建数据库 | CREATE DATABASE [IF NOT EXISTS] db_name [CHARACTER SET charset_name]; | 创建新数据库 | CREATE DATABASE IF NOT EXISTS mydb CHARACTER SET utf8mb4; | 默认字符集为 utf8mb4；不支持 COLLATE 子句（部分版本支持）。 |
| 使用数据库 | USE db_name; | 切换当前会话的默认数据库 | USE mydb; | 若数据库不存在，返回错误。 |
| 删除数据库 | DROP DATABASE [IF EXISTS] db_name; | 删除整个数据库及其所有表 | DROP DATABASE IF EXISTS mydb; | 操作不可逆；需 DROP 权限。 |
| 创建表 | CREATE TABLE [IF NOT EXISTS] table_name (col_def [, constraint]) [ENGINE=InnoDB]; | 定义表结构 | CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(50)); | 必须显式指定主键（建议使用 AUTO_INCREMENT 或业务唯一 ID）；不支持 FOREIGN KEY。 |
| 查看表结构 | DESCRIBE table_name; 或 SHOW CREATE TABLE table_name; | 查看列定义或完整建表语句 | DESCRIBE users; | DESC 是 DESCRIBE 的别名。 |
| 修改表结构 | ALTER TABLE table_name ADD COLUMN col_name type;
ALTER TABLE table_name DROP COLUMN col_name;
ALTER TABLE table_name MODIFY COLUMN col_name new_type; | 在线增删改列（部分操作） | ALTER TABLE users ADD COLUMN email VARCHAR(100); | 支持大部分 DDL 在线执行（不阻塞读写）；但 MODIFY 到更大类型可能受限。 |
| 删除表 | DROP TABLE [IF EXISTS] table_name; | 删除整张表 | DROP TABLE IF EXISTS users; | 同时删除所有索引和数据；不可回滚。 |
3.2 DML 操作（INSERT / UPDATE / DELETE）
| 方法/语句名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 插入单行 | INSERT INTO table_name [(col1, col2)] VALUES (val1, val2); | 向表中插入一条记录 | INSERT INTO users (id, name) VALUES (1, 'Alice'); | 主键冲突将报错（除非使用 ON DUPLICATE KEY UPDATE）。 |
| 批量插入 | INSERT INTO table_name VALUES (v1), (v2), ...; | 一次插入多行，提升性能 | INSERT INTO users VALUES (2, 'Bob'), (3, 'Charlie'); | 推荐批量提交（如每 1k～10k 行一个事务），避免大事务。 |
| 更新数据 | UPDATE table_name SET col = val WHERE condition; | 修改满足条件的行 | UPDATE users SET name = 'Alice Smith' WHERE id = 1; | 若省略 WHERE，将更新全表；需谨慎。 |
| 删除数据 | DELETE FROM table_name WHERE condition; | 删除满足条件的行 | DELETE FROM users WHERE id = 2; | 不支持 TRUNCATE TABLE 的快速释放（实际是 DDL，但 TiDB 支持）；TRUNCATE 更高效清空表。 |
| 替换插入 | REPLACE INTO table_name VALUES (...); | 若主键冲突则先删后插 | REPLACE INTO users VALUES (1, 'New Alice'); | 会产生 DELETE + INSERT 两个操作，可能影响自增 ID 连续性。 |
| 冲突更新 | INSERT INTO ... ON DUPLICATE KEY UPDATE col = val; | 主键/唯一键冲突时更新指定列 | INSERT INTO users (id, name) VALUES (1, 'Alice') ON DUPLICATE KEY UPDATE name = 'Alice'; | 仅当存在唯一约束冲突时触发 UPDATE。 |
3.3 查询语句（SELECT 与 JOIN）
| 方法/语句名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 基本查询 | SELECT select_expr FROM table_name [WHERE condition]; | 从表中检索数据 | SELECT name FROM users WHERE id > 1; | 支持 * 通配符；建议显式指定列以提升性能。 |
| 内连接 | SELECT ... FROM t1 INNER JOIN t2 ON t1.id = t2.user_id; | 返回两表匹配的行 | SELECT u.name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id; | 支持 JOIN、INNER JOIN、CROSS JOIN。 |
| 左外连接 | SELECT ... FROM t1 LEFT JOIN t2 ON ...; | 返回左表全部行，右表无匹配则 NULL | SELECT u.name, o.amount FROM users u LEFT JOIN orders o ON u.id = o.user_id; | 不支持 RIGHT JOIN（可转换为 LEFT JOIN）。 |
| 子查询 | SELECT * FROM t1 WHERE id IN (SELECT user_id FROM t2); | 嵌套查询 | SELECT name FROM users WHERE id IN (SELECT user_id FROM orders WHERE amount > 100); | 支持相关子查询；复杂子查询可能影响性能。 |
| 聚合函数 | SELECT COUNT(*), AVG(price) FROM products; | 统计计算 | SELECT department, AVG(salary) FROM employees GROUP BY department; | 支持 COUNT、SUM、AVG、MIN、MAX 等。 |
| 排序与分页 | SELECT ... ORDER BY col [ASC | DESC] LIMIT offset, count; | 控制结果顺序与数量 | SELECT * FROM users ORDER BY id DESC LIMIT 10 OFFSET 20; | OFFSET 值较大时性能下降（需回表），建议配合覆盖索引使用。 |
3.4 索引管理与优化建议
| 方法/语句名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 创建索引 | CREATE INDEX index_name ON table_name (col1, col2); | 为列添加二级索引 | CREATE INDEX idx_name ON users (name); | 索引会降低写入性能；避免过多冗余索引。 |
| 创建唯一索引 | CREATE UNIQUE INDEX uniq_email ON users (email); | 确保列值唯一 | CREATE UNIQUE INDEX uniq_email ON users (email); | 插入重复值将报错。 |
| 查看索引 | SHOW INDEX FROM table_name; | 列出表的所有索引 | SHOW INDEX FROM users; | 包含主键（PRIMARY）和二级索引。 |
| 删除索引 | DROP INDEX index_name ON table_name; | 移除索引 | DROP INDEX idx_name ON users; | 删除后查询可能变慢；在线操作，不影响读写。 |
| 前缀索引 | CREATE INDEX idx_prefix ON table_name (col(20)); | 对字符串列前 N 字符建索引 | CREATE INDEX idx_name_prefix ON users (name(10)); | 节省存储空间；但可能降低选择性。 |
| 覆盖索引建议 | 查询字段全部包含在索引中，避免回表 | SELECT id, name FROM users WHERE name = 'Alice';（若 idx(name, id)） | 可显著提升点查性能；设计索引时考虑查询模式。 | |
| 避免索引失效 | 不在索引列上使用函数、类型转换、!=、NOT IN 等 | SELECT * FROM users WHERE UPPER(name) = 'ALICE';（无法用 name 索引） | 应改写为 name = 'Alice'；使用 EXPLAIN 验证执行计划。 | |
第四章：TiDB 高级功能
4.1 分布式事务（乐观/悲观事务模型）
| 概念/方法名称 | 说明 | 代码示例 | 注意事项 |
|---|
| 乐观事务（默认） | 事务在提交时才检查冲突，适用于低冲突场景；使用 Percolator 模型。 | BEGIN; UPDATE accounts SET balance = balance - 100 WHERE id = 1; COMMIT; | 高并发写同一行时易触发 Write Conflict 错误，需应用层重试。 |
| 悲观事务 | 在 DML 执行时加锁，避免提交时冲突，行为更接近 MySQL。 | SET tidb_txn_mode = 'pessimistic'; BEGIN; UPDATE accounts SET balance = balance - 100 WHERE id = 1; COMMIT; | 减少重试，但可能引入死锁（TiDB 自动检测并回滚一方）。 |
| 设置事务模式（会话级） | SET tidb_txn_mode = 'optimistic' | 'pessimistic'; | SET tidb_txn_mode = 'pessimistic'; | 仅对当前会话生效；全局可通过配置文件设置 txn-mode。 |
| 事务重试机制 | 应用需捕获 Error 8002 (WriteConflict) 并重试整个事务。 | 应用逻辑中使用循环重试（如 Go 的 retry.Do） | 不可只重试 COMMIT；必须重放整个事务逻辑。 |
| 大事务限制 | 单事务建议 ≤ 100 MB 或 5,000 条修改；超限可能导致 OOM 或 Region 分裂。 | 避免 INSERT INTO ... SELECT * FROM huge_table; | 可通过 tidb_batch_commit 或分页提交拆分大事务。 |
4.2 分区表与 Region 管理
| 概念/方法名称 | 说明 | 代码示例 | 注意事项 |
|---|
| Range 分区表 | 按范围划分数据，适用于时间序列或 ID 区间场景。 | CREATE TABLE logs (ts DATETIME, msg TEXT) PARTITION BY RANGE (YEAR(ts)) (PARTITION p2023 VALUES LESS THAN (2024), PARTITION p2024 VALUES LESS THAN (2025)); | 支持 RANGE、HASH、LIST 分区；不支持子分区。 |
| 分区裁剪（Pruning） | 查询时自动跳过无关分区，提升性能。 | SELECT * FROM logs WHERE ts BETWEEN '2023-01-01' AND '2023-12-31'; → 仅扫描 p2023 | 需确保 WHERE 条件能推导出分区范围，否则全扫。 |
| Region 概念 | TiKV 中数据按 96MB（默认）切分为 Region，是复制和调度的最小单位。 | 无需用户直接操作 | Region 过多会增加 PD 负担；过少影响并行度。 |
| 手动分裂 Region | 使用 SPLIT TABLE table_name BETWEEN (...) AND (...) REGIONS count; | SPLIT TABLE users BETWEEN (0) AND (1000000) REGIONS 10; | 用于预分片，避免写入热点（如单调递增主键）。 |
| 查看 Region 分布 | SHOW TABLE table_name REGIONS; | SHOW TABLE users REGIONS; | 可观察 Leader/Peer 分布，辅助诊断热点问题。 |
4.3 统计信息与执行计划
| 方法/概念名称 | 语法 / 说明 | 用途 | 代码示例 | 注意事项 |
|---|
| 收集统计信息 | ANALYZE TABLE table_name; | 更新列和索引的直方图、NDV 等，供优化器使用 | ANALYZE TABLE orders; | 默认自动收集（tidb_auto_analyze_ratio=0.5）；大表可手动触发。 |
| 查看统计信息 | SHOW STATS_META;
SHOW STATS_HISTOGRAMS WHERE table_name='orders'; | 诊断统计信息是否缺失或过期 | SHOW STATS_BUCKETS WHERE table_name='orders' AND column_name='status'; | 若 modify_count / row_count > 0.3，建议手动 ANALYZE。 |
| 查看执行计划 | EXPLAIN [ANALYZE] SELECT ...; | 显示查询的执行路径、算子、代价估算 | EXPLAIN SELECT * FROM users WHERE name = 'Alice'; | EXPLAIN ANALYZE 会实际执行并返回运行时信息（如 cop_time）。 |
| 执行计划缓存 | TiDB 自动缓存参数化查询的计划（v6.0+ 默认开启） | 提升重复查询性能 | 无需显式操作 | 若数据分布变化大，可能缓存劣质计划；可通过 ignore_plan_cache() hint 禁用。 |
| 优化器 Hint | 强制指定访问路径或连接顺序 | SELECT /*+ USE_INDEX(t, idx_name) */ * FROM t WHERE ...; | SELECT /*+ HASH_JOIN(orders, users) */ ... | 仅用于调试或临时绕过优化器缺陷；慎用于生产。 |
4.4 视图、存储过程与函数支持情况
| 功能类型 | 支持情况 | 说明 | 代码示例 | 注意事项 |
|---|
| 视图（VIEW） | ✅ 完全支持 | 虚拟表，基于 SELECT 定义 | CREATE VIEW active_users AS SELECT id, name FROM users WHERE status = 'active'; | 不支持物化视图；每次查询实时计算。 |
| 存储过程 | ❌ 不支持 | 无法创建或调用存储过程 | CREATE PROCEDURE ... → 报错 | 应将业务逻辑移至应用层。 |
| 存储函数（UDF） | ❌ 不支持 | 无法创建用户自定义函数 | CREATE FUNCTION ... → 报错 | 仅支持内置函数（如 DATE_FORMAT、JSON_EXTRACT）。 |
| 触发器（TRIGGER） | ❌ 不支持 | 无法定义 INSERT/UPDATE/DELETE 触发逻辑 | CREATE TRIGGER ... → 报错 | 需通过应用层或 CDC 工具实现类似逻辑。 |
| 内置函数兼容性 | ⚠️ 部分支持 | 支持大部分 MySQL 5.7 常用函数 | SELECT NOW(), CONCAT('a','b'), JSON_EXTRACT('{"k":"v"}', '$.k'); | 不支持 GET_LOCK、RELEASE_LOCK、SLEEP（部分版本支持 SLEEP 用于测试）。 |
| 事件调度器（Event） | ❌ 不支持 | 无法创建定时任务 | CREATE EVENT ... → 报错 | 应使用外部调度系统（如 cron、Airflow）。 |
第五章：TiDB 命令行工具详解
5.1 tiup 命令行工具
| 方法/命令名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 安装 TiUP | curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh | 安装 TiUP 包管理器 | 如上 | 需 bash 和 curl；安装后执行 source ~/.bashrc 生效 |
| 查看组件列表 | tiup list tidb | 列出可用的 TiDB 版本 | tiup list tidb | 可加 --verbose 查看详细信息 |
| 启动 playground | tiup playground [version] [--db N] [--kv N] [--pd N] [--tiflash N] | 快速启动本地测试集群 | tiup playground v7.5.0 --db 2 --kv 3 | 首次运行自动下载组件；仅用于开发测试 |
| 部署生产集群 | tiup cluster deploy <name> <version> topology.yaml [-u user] [-p] | 部署分布式集群 | tiup cluster deploy prod v7.5.0 topo.yaml -u tidb -p | 需提前配置 SSH 免密登录；topo.yaml 需符合规范 |
| 查看集群状态 | tiup cluster display <name> | 显示各组件运行状态、IP、端口 | tiup cluster display prod | ”Up” 表示正常；可结合 grep 过滤 |
| 扩容节点 | tiup cluster scale-out <name> scale.yaml [-u user] [-p] | 添加新节点（如 TiKV、TiFlash） | tiup cluster scale-out prod scale-tiflash.yaml | 扩容后需等待数据均衡（可通过 PD 监控观察） |
| 缩容节点 | tiup cluster scale-in <name> --node <ip:port> | 安全下线指定节点 | tiup cluster scale-in prod --node 192.168.1.10:20160 | 自动迁移数据；不可直接 kill 进程 |
| 升级集群 | tiup cluster upgrade <name> <new_version> | 在线滚动升级 | tiup cluster upgrade prod v7.6.0 | 建议先在测试环境验证兼容性 |
5.2 tidb-cli（MySQL 客户端连接）
| 方法/命令名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 连接 TiDB | mysql -h <host> -P <port> -u <user> [-p] [database] | 使用 MySQL 客户端连接 TiDB | mysql -h 127.0.0.1 -P 4000 -u root test | 默认无密码；若启用密码，加 -p 后输入 |
| 执行单条 SQL | mysql -h ... -e "SQL" | 非交互式执行 SQL | mysql -h 127.0.0.1 -P 4000 -e "SHOW DATABASES;" | 适用于脚本自动化 |
| 启用 TLS 连接 | mysql --ssl-mode=REQUIRED -h ... | 加密客户端与 TiDB 通信 | mysql --ssl-mode=REQUIRED -h tidb.example.com -P 4000 -u root | 需 TiDB 配置 security.cert-allowed-cn 等参数 |
| 查看当前会话 | SELECT CONNECTION_ID(), USER(), DATABASE(); | 获取连接上下文信息 | 在 mysql CLI 中执行 | 用于排查连接归属 |
| 设置会话变量 | SET tidb_txn_mode = 'pessimistic'; | 动态调整事务模式等 | SET autocommit = 0; | 仅对当前连接生效 |
5.3 pd-ctl（Placement Driver 控制工具）
| 方法/命令名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 启动 pd-ctl | tiup ctl:v7.5.0 pd -u http://<pd-ip>:2379 | 连接 PD 集群进行管理 | tiup ctl:v7.5.0 pd -u http://192.168.1.10:2379 | 需指定 PD 节点地址；支持多地址逗号分隔 |
| 查看成员状态 | member | 列出所有 PD 成员及其健康状态 | » member | 返回 leader 和 followers 信息 |
| 查看 Region 信息 | region [region_id] | 查看 Region 的 key 范围、副本位置 | » region 1001 | 可用于诊断热点或副本缺失 |
| 查看 Store 状态 | store [store_id] | 查看 TiKV 节点（Store）状态 | » store 1 | 状态为 “Up” 表示正常；“Offline” 表示正在下线 |
| 手动分裂 Region | operator add split-region <region_id> --policy=approximate | 强制分裂指定 Region | » operator add split-region 1001 --policy=approximate | 用于缓解大 Region 或热点问题 |
| 设置调度限制 | config set max-snapshot-count 3 | 调整 PD 调度参数 | » config set leader-schedule-limit 8 | 修改后立即生效；建议参考官方调优指南 |
5.4 tikv-ctl（TiKV 底层数据操作）
| 方法/命令名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| 启动 tikv-ctl | tiup ctl:v7.5.0 tikv --db /path/to/tikv/db --ca-path ... | 直接操作 TiKV RocksDB 实例 | tiup ctl:v7.5.0 tikv --db /tidb-data/tikv-20160/db --config /etc/tikv.toml | 需登录到 TiKV 所在机器；路径来自 tikv-server 配置 |
| 查看 MVCC 数据 | mvcc get --key <encoded_key> | 查看某 key 的多版本数据 | » mvcc get --key 7480000000000000FF3B5F728000000000FF00000100 | key 需为 TiDB 编码格式；通常用于故障恢复 |
| 查看 Region 本地信息 | raft region <region_id> | 查看本地 Store 上 Region 的 Raft 状态 | » raft region 1001 | 仅显示本机持有的 Region |
| 强制 compact | compact-cluster | 触发 RocksDB compaction，回收空间 | » compact-cluster | 消耗 I/O 和 CPU；建议在低峰期执行 |
| 解码 TiDB Key | decode --key <hex_key> | 将十六进制 key 解码为表/索引/行信息 | » decode --key 7480000000000000FF3B5F728000000000FF00000100 | 输出如 table_id:59, index_id:1, handle:1 |
5.5 dumpling 与 lightning（数据导入导出）
| 工具/方法名称 | 语法 | 用途 | 代码示例 | 注意事项 |
|---|
| Dumpling 导出 | tiup dumpling -u root -P 4000 -h 127.0.0.1 -o ./backup --filetype sql | 逻辑导出 TiDB 数据为 SQL/CSV | tiup dumpling -h 192.168.1.10 -P 4000 -u root -p -T mydb.users -o ./backup | 支持按表、库过滤；默认并发导出；不锁表 |
| Lightning 导入（Local Backend） | tiup tidb-lightning -config lightning.toml | 高速导入 SQL/CSV 到 TiDB（绕过 SQL 层） | 配置文件中指定 [mydumper] data-source-dir = "./backup" | 仅适用于空表或 TRUNCATE 后；不可用于增量导入 |
| Lightning 配置关键项 | [tidb] host/port/user/password
[mydumper] data-source-dir
[tikv-importer] backend = "local" | 定义源、目标、导入方式 | 见官方文档模板 | Local 模式最快但需停写；Importer 模式已废弃 |
| 校验数据一致性 | tiup dumpling ... --consistency snapshot | 导出时基于同一快照保证一致性 | tiup dumpling --consistency snapshot -o ./consistent_backup | 默认使用 flush tables with read lock（不推荐）；snapshot 更安全 |
| 导出过滤条件 | --where "id > 1000" | 仅导出满足条件的数据 | tiup dumpling -T orders --where "create_time > '2023-01-01'" | 适用于分片归档或子集迁移 |
| 并发控制 | --threads 16 | 控制 Dumpling/Lightning 并发数 | tiup dumpling --threads 32 -o ./fast_backup | 根据源/目标负载调整；过高可能压垮集群 |
第六章：TiDB 运维与监控
6.1 集群扩缩容操作
| 操作名称 | 操作细节 | 注意事项 |
|---|
| 扩容 TiDB 节点 | 编写 scale-out.yaml，包含新 TiDB 实例的 host、port；执行 tiup cluster scale-out <cluster-name> scale-out.yaml -u <user> -p | 新节点自动注册到 PD；连接层（如 HAProxy）需手动更新后端列表 |
| 扩容 TiKV 节点 | 在 scale-out.yaml 中定义新 TiKV 实例；执行 tiup cluster scale-out；PD 自动将 Region 均衡到新节点 | 扩容后需等待数小时完成数据均衡；可通过 pd-ctl store 观察 Leader/Region 分布 |
| 扩容 TiFlash 节点 | 类似 TiKV，但需指定 tiflash_servers；扩容后需在 SQL 层执行 ALTER TABLE t SET TIFLASH REPLICA N; 启用副本 | 若未显式设置副本数，新 TiFlash 节点不会同步数据 |
| 缩容 TiDB 节点 | 执行 tiup cluster scale-in <cluster-name> --node <ip:port>（port 为 4000） | 仅移除组件；应用需提前停止向该节点发请求 |
| 缩容 TiKV/TiFlash 节点 | 执行 tiup cluster scale-in ... --node <ip:20160>（TiKV）或 <ip:3930>（TiFlash） | PD 先迁移该 Store 上所有 Region 副本，再下线；过程可能耗时较长（取决于数据量） |
| 验证扩缩容结果 | 执行 tiup cluster display <cluster-name> 查看节点状态；使用 pd-ctl store 确认 Store 状态为 “Up” 或 “Offline” → “Tombstone” | 缩容完成后，Store 状态应变为 “Tombstone”，可安全清理磁盘数据 |
6.2 备份与恢复（BR 工具）
| 操作名称 | 语法 / 操作细节 | 用途 | 代码示例 | 注意事项 |
|---|
| 安装 BR 工具 | tiup install br | 安装备份恢复工具 | tiup install br:v7.5.0 | 需与集群版本一致 |
| 全量备份 | tiup br backup full --pd "<pd-addrs>" -s "local:///backup" --ratelimit 120 --concurrency 4 | 备份整个集群到本地/NFS/S3 | tiup br backup full --pd "192.168.1.10:2379" -s "s3://mybucket/backup?access-key=...&secret-access-key=..." | -s 支持 local、s3、gcs、hdfs；--ratelimit 控制 I/O 带宽（MB/s） |
| 库级备份 | tiup br backup db --db mydb --pd ... -s ... | 仅备份指定数据库 | tiup br backup db --db orders --pd ... -s local:///backup/orders | 表名可用 --table 进一步过滤 |
| 全量恢复 | tiup br restore full --pd "<pd-addrs>" -s "local:///backup" --ratelimit 120 | 将备份数据恢复到新集群 | tiup br restore full --pd "192.168.1.20:2379" -s "s3://mybucket/backup" | 目标集群必须为空；恢复期间禁止写入 |
| 增量备份 | tiup br backup full --pd ... -s ... --lastbackupts <ts> | 基于上次备份时间戳增量备份 | 需先记录 br backup 输出中的 Commit TS | 增量恢复需按顺序应用多个增量包 |
| 校验备份一致性 | tiup br validate decode --pd ... -s ... | 验证备份文件是否可读 | tiup br validate decode --pd "192.168.1.10:2379" -s local:///backup | 不执行实际恢复，仅解析元数据 |
| 备份加密 | --crypter.method aes128-ctr --crypter.key <hex_key> | 对备份数据加密 | tiup br backup full ... --crypter.method aes128-ctr --crypter.key 0123456789abcdef0123456789abcdef | 恢复时需提供相同密钥；密钥长度需匹配算法 |
6.3 监控体系（Prometheus + Grafana）
| 组件/操作 | 说明 | 配置/访问方式 | 注意事项 |
|---|
| Prometheus | 采集 TiDB/PD/TiKV/TiFlash 等组件的指标（通过 HTTP /metrics 接口） | 由 TiUP 部署时自动配置；默认端口 9090 | 数据保留时间默认 15 天；可修改 prometheus.yml 调整 scrape_interval |
| Grafana | 可视化监控面板，展示 QPS、延迟、Region 状态、硬件资源等 | 访问 http://<grafana-ip>:3000（默认账号 admin/admin） | 支持导入自定义 Dashboard；官方提供 “TiDB Overview”、“PD”、“TiKV” 等模板 |
| Alertmanager | 基于 Prometheus 规则触发告警（如节点宕机、磁盘满） | 告警规则位于 rules/*.rules.yml；通知渠道需配置 webhook/email | 建议配置企业微信/钉钉/Webhook 通知 |
| 关键监控指标 | - QPS / Latency
- TiKV CPU / Disk IO
- PD Scheduler Ops
- TiFlash Sync Progress | 在 Grafana “TiDB Overview” 面板查看 | 突增的 “Commit Failures” 或 “Write Conflict” 需重点关注 |
| 自定义监控 | 在 tidb-monitor-initializer 中添加额外 exporter（如 node_exporter） | 修改 monitoring_servers 拓扑配置 | 需确保网络策略允许 scrape |
| 日志集成（可选） | 通过 Loki + Promtail 收集日志，与 Grafana 联动 | 非 TiUP 默认组件；需手动部署 | 适用于集中日志分析场景 |
6.4 常见故障排查与日志分析
| 故障现象 | 排查步骤 | 日志位置 | 注意事项 |
|---|
| TiDB 连接拒绝 | 1. 检查 tiup cluster display 状态
2. telnet <tidb-ip> 4000
3. 查看 TiDB 日志是否有 panic | /tidb-deploy/tidb-4000/log/tidb.log | 可能因 OOM 被 kill；检查系统 dmesg |
| 写入缓慢 / 超时 | 1. EXPLAIN ANALYZE 查执行计划
2. 检查 Grafana 中 TiKV coprocessor 延迟
3. pd-ctl region --jq=".regions[] | select(.written_bytes > 1e8)" 查热点 | TiKV 日志：/tidb-data/tikv-20160/log/tikv.log | 热点通常由单调主键引起；考虑 SHARD_ROW_ID_BITS 或业务分片 |
| PD Leader 无法选举 | 1. pd-ctl member 查成员状态
2. 检查网络连通性（2380 端口）
3. 查看 PD 日志 Raft 错误 | /tidb-deploy/pd-2379/log/pd.log | PD 节点数必须为奇数；偶数节点易脑裂 |
| TiKV Store Down | 1. pd-ctl store 查状态
2. 检查机器是否宕机
3. 查看 TiKV 日志是否 RocksDB stall | 同上 | 若长时间 “Down”，PD 会自动补副本；需尽快恢复或缩容 |
| BR 备份失败 | 1. 检查 -s 路径权限
2. 查看 BR 日志中的 error
3. 确认 PD 地址可达 | BR 命令行直接输出错误；无独立日志文件 | S3 备份需确认 IAM 权限和 endpoint 正确 |
| 日志关键词 | - “write conflict”
- “region is unavailable”
- “raftstore is busy”
- “coprocessor timeout” | 所有组件日志均位于 /tidb-deploy/*/log/ 或 /tidb-data/*/log/ | 使用 grep -r "error" /tidb-deploy/*/log/ 快速定位 |
第七章：性能调优与最佳实践
7.1 SQL 执行计划分析（EXPLAIN）
| 方法/命令名称 | 语法 / 说明 | 用途 | 代码示例 | 注意事项 |
|---|
| 基础执行计划 | EXPLAIN SELECT ...; | 显示查询的逻辑执行计划（未实际执行） | EXPLAIN SELECT * FROM users WHERE name = 'Alice'; | 输出包含算子类型（如 TableReader、IndexLookUp）、访问对象、估算行数等 |
| 实际执行分析 | EXPLAIN ANALYZE SELECT ...; | 实际执行查询并返回运行时统计信息 | EXPLAIN ANALYZE SELECT COUNT(*) FROM orders WHERE status = 'paid'; | 包含 actRows（实际行数）、execution info（cop_time、proc_time）、memory 等关键指标 |
| 查看 Plan Cache | SELECT * FROM information_schema.statements_summary WHERE digest_text LIKE '%SELECT%users%'; | 分析已缓存计划的性能表现 | 可结合 plan_digest 关联 statements_summary_history | v6.0+ 默认启用计划缓存；劣质计划可通过 ignore_plan_cache() hint 绕过 |
| 强制索引访问 | SELECT /*+ USE_INDEX(t, idx_name) */ * FROM t WHERE ...; | 覆盖优化器选择，强制使用指定索引 | SELECT /*+ USE_INDEX(users, idx_name) */ * FROM users WHERE name = 'Alice'; | 仅用于临时调试；长期应通过更新统计信息或改写 SQL 解决 |
| 避免全表扫描 | 确保 WHERE 条件命中索引；避免在索引列上使用函数 | 提升点查/范围查询性能 | 改写 WHERE UPPER(name) = 'ALICE' → WHERE name = 'Alice' | 使用 EXPLAIN 验证是否出现 TableFullScan |
| 查看 Coprocessor 负载 | 在 EXPLAIN ANALYZE 中观察 copr_task 数量与耗时 | 诊断 TiKV 层计算压力 | 若 cop_time >> proc_time，说明 TiKV 成为瓶颈 | 可通过增加 TiKV 节点或优化索引缓解 |
7.2 热点问题识别与解决
| 操作/方法名称 | 操作细节 / 说明 | 用途 | 代码示例 / 命令 | 注意事项 |
|---|
| 识别写入热点 | 在 Grafana “TiKV-Details” → “Hot Region” 面板查看高 written_bytes 或 written_keys 的 Region | 定位写入瓶颈 | 或使用 pd-ctl hot read / pd-ctl hot write | 热点通常集中在单个 Region，表现为某 TiKV CPU 或 IO 突增 |
| 识别读热点 | 同上，关注 read_bytes / read_keys | 定位高频读取区域 | pd-ctl region --jq=".regions[] | select(.read_keys > 1e6)" | 可能由缓存穿透或大促流量引起 |
| 主键设计优化 | 避免单调递增主键（如 AUTO_INCREMENT）；改用 SHARD_ROW_ID_BITS=N 或业务分片 ID | 打散写入负载 | CREATE TABLE t (id BIGINT PRIMARY KEY) SHARD_ROW_ID_BITS=4; | SHARD_ROW_ID_BITS 最大为 15；会牺牲主键有序性 |
| 预分裂 Region | 在建表后立即分裂，避免初期写入集中在单 Region | 缓解新表热点 | SPLIT TABLE t BETWEEN (0) AND (10000000) REGIONS 10; | 分裂范围需覆盖预期数据分布 |
| 使用 AUTO_RANDOM | 替代 AUTO_INCREMENT，自动打散主键 | 兼顾唯一性与写入分散 | CREATE TABLE t (id BIGINT PRIMARY KEY AUTO_RANDOM, name VARCHAR(50)); | 仅适用于整型主键；不可与 SHARD_ROW_ID_BITS 同用 |
| 热点调度干预 | 通过 PD 配置限制热点调度速度 | 避免频繁调度引发抖动 | pd-ctl config set hot-region-schedule-limit 2 | 默认值通常合理；仅在调度过于激进时调整 |
7.3 资源控制（Resource Control）
| 功能/命令名称 | 语法 / 说明 | 用途 | 代码示例 | 注意事项 |
|---|
| 创建资源组 | CREATE RESOURCE GROUP rg_oltp RU_PER_SEC = 500; | 定义资源单元（RU）配额 | CREATE RESOURCE GROUP rg_report RU_PER_SEC = 200; | v7.1+ 企业版支持；社区版不支持 Resource Control |
| 绑定用户到资源组 | ALTER USER 'app_user'@'%' RESOURCE GROUP rg_oltp; | 限制用户 SQL 消耗的资源 | ALTER USER 'report_user'@'%' RESOURCE GROUP rg_report; | 未绑定用户使用默认资源组（default） |
| 查看资源组状态 | SELECT * FROM information_schema.resource_groups; | 监控各组 RU 使用情况 | SELECT NAME, RU_PER_SEC, PRIORITY FROM information_schema.resource_groups; | RU（Request Unit）综合衡量 CPU、IO、网络等资源 |
| 动态调整配额 | ALTER RESOURCE GROUP rg_oltp RU_PER_SEC = 800; | 运行时调整资源分配 | 无需重启服务 | 调整立即生效；可用于应对流量高峰 |
| 优先级设置 | CREATE RESOURCE GROUP rg_high PRIORITY = HIGH; | 高优先级任务优先调度 | 适用于核心交易链路 | 优先级仅影响调度顺序，不增加 RU 配额 |
| 资源隔离效果验证 | 通过 Grafana “Resource Control” 面板观察 RU 消耗曲线 | 验证隔离是否生效 | 确保 report 查询不挤占 OLTP 资源 | 需配合 QPS 和延迟指标综合判断 |
⚠️ 注意：Resource Control 为企业版功能，社区版用户需通过应用层限流或 Kubernetes 资源限制实现类似效果。
7.4 配置参数调优建议
| 参数类别 | 参数名称 | 推荐值 / 说明 | 用途 | 注意事项 |
|---|
| TiDB 层 | tidb_distsql_scan_concurrency | 默认 15；可增至 30～50（SSD 环境） | 控制单条 SQL 并发扫描 Region 数 | 过高可能压垮 TiKV；需结合 tidb_executor_concurrency 调整 |
| TiDB 层 | tidb_mem_quota_query | 默认 1GB；复杂分析可设为 4～8GB | 单查询内存上限 | 超限会触发 spill-to-disk 或报错；需监控 OOM |
| TiKV 层 | raftstore.apply-pool-size | 默认 2；CPU 核数 ≥ 16 时可设为 4 | 提升 Raft 日志 apply 并发 | 过高增加上下文切换开销 |
| TiKV 层 | rocksdb.max-background-jobs | 默认 8；NVMe SSD 可设为 12～16 | 提升 RocksDB compaction 并发 | 需确保 I/O 能力充足 |
| PD 层 | schedule.max-merge-region-keys | 默认 20000；可降低至 5000 | 减少小 Region 合并，缓解调度压力 | 小 Region 更利于负载均衡，但增加元数据量 |
| 全局 | oom-action（TiDB） | 默认 cancel；不建议改为 log | 内存超限时取消查询而非 kill 进程 | 避免整个 TiDB 实例崩溃 |
| 监控告警 | alert.rules.yml 中配置 TiKV_store_size > 80% | 触发磁盘容量告警 | 预防写满宕机 | 建议预留 20% 空间用于 compaction |
| 日志级别 | log.level = "info"（生产） | 避免 debug 日志占用 I/O | 降低日志开销 | 故障排查时可临时切为 “debug” |
💡 调优原则：
- 先优化 SQL 和索引，再调参数；
- 每次只调整 1～2 个参数，观察效果；
- 所有修改应通过 TiUP 更新配置并滚动重启（
tiup cluster reload <name>）。