我让 Codex 自己维护 NoteDeep 官方文档
2026/8/2 4:54:51
本篇文章将详细介绍pt-table-checksum这款用于MySQL主从数据一致性校验的工具。以下是其核心要点总结：
🔧 工具简介
pt-table-checksum是 Percona Toolkit 工具包中的一个重要工具，专门用于校验MySQL主库和从库之间的数据是否一致。其基本原理是在主库执行校验语句（binlog_format=STATEMENT），并利用复制机制传递到从库，通过比对主从双方的校验值来发现差异。
⚙️ 核心工作原理
- 分块校验：工具会将每个需要校验的表按照索引（优先主键或唯一键）切分成多个“数据块”（chunks），逐块进行校验，以避免对数据库造成过大负载或复制延迟。
- 动态调整：根据
--chunk-time参数（默认0.5秒）动态调整每个数据块的大小，以适应当前服务器的性能。 - 从库感知：工具会持续监控从库的复制延迟。如果延迟过大或从库出错，校验会暂停等待。它还具备错误恢复能力，比如查询被中断后会重试。
- 智能暂停与恢复：校验完一个表的所有块后，会等待所有从库执行完毕，再进行结果比对。支持使用
--resume参数从中断处继续执行。
📋 主要使用限制
- 复制格式要求：要求主从复制基于STATEMENT格式。由于MySQL限制，主库设置的
binlog_format=STATEMENT不会传递给从库，因此如果从库自身的binlog_format是ROW，则无法校验该从库的下级从库。 - 结构一致性假设：工具假设主从的数据库和表结构完全一致。如果从库缺少库或表结构不同，可能导致复制中断。
📊 结果解读
执行后的输出主要有两种格式，关键列含义如下：
1. 标准输出（不带--replicate-check-only）
结果以表格形式呈现，每张表一行。
| 列名 | 含义说明 |
|---|---|
| TS | 完成该表校验的时间戳 |
| ERRORS | 校验过程中出现的错误和警告数量 |
| DIFFS | 核心指标：主从数据不一致的数据块数量。为0则表示一致 |
| ROWS | 校验的数据行数 |
| CHUNKS | 表被分成的块数 |
| SKIPPED | 跳过的块数（可能因索引、锁超时等问题） |
| TIME | 校验耗时 |
| TABLE | 被校验的表名（含库名） |
2. 差异详情输出（带--replicate-check-only）
仅输出发现不一致的从库和具体数据块信息，格式更详细，包含差异表名、块号、行数差、CRC校验差等。
⚡ 常用参数速查
这里列举一些最常用和关键的参数：
| 参数 | 说明与用途 |
|---|---|
--replicate=<库名.表名> | 核心参数。指定存储校验结果的表，默认为percona.checksums。 |
--no-replicate-check | 只执行校验并写入结果表，不立即对比主从差异。常用于定时任务。 |
--replicate-check-only | 不进行新校验，仅基于已有的结果表检查差异并输出。常用于监控。 |
--databases/-d | 指定要校验的数据库。 |
--tables/-t | 指定要校验的表。 |
--where | 只校验符合WHERE条件的数据（如只校验最近一天的数据），可大幅提升效率。 |
--no-check-binlog-format | 如果从库binlog格式不是STATEMENT，需要指定此参数跳过检查。 |
--no-check-replication-filters | 如果从库配置了复制过滤规则，需要指定此参数。 |
--recursion-method | 指定工具发现从库的方法（如processlist,hosts），当自动发现失败时使用。 |
💡 使用场景与建议
- 定期校验：结合
--no-replicate-check在业务低峰期执行完整校验，再通过--replicate-check-only快速检查结果，适合集成到监控系统（如Zabbix）。 - 校验大数据表：充分利用
--where条件，只校验增量或特定范围的数据，减少开销。 - 注意事项：务必确保主从表结构一致，并注意从库的binlog格式可能带来的限制。首次使用建议在测试环境充分验证。
links
https://www.modb.pro/db/56033