pt-table-checksum主从切换后报错主因是环境未对齐：需确认所有从库seconds_behind_master为0、slave_io_running和slave_sql_running均为yes；report_host/report_port必须显式配置；从库需开放远程连接且校验用户具备replication client+select权限；row模式下必须加--no-check-binlog-format参数。
pt-table-checksum 在主从切换后报错，不是工具本身坏了，而是环境没对齐——多数情况根本没走到“校验数据”那步，就在连接、权限或状态判断上卡死了。
检查 SHOW SLAVE STATUS\G 是否真为同步就绪
pt-table-checksum 默认依赖从库处于健康复制状态，一旦 Slave_IO_Running 或 Slave_SQL_Running 为 No，它会直接退出并报类似 Cannot connect to slave 的错误（实际是检测到复制线程异常）。
- 必须手动确认所有从库都满足：
Seconds_Behind_Master 显示为 0（不是 NULL）
Slave_IO_Running 和 Slave_SQL_Running 都是 YesSlave_SQL_Running_State 是 Slave has read all relay log，而非 Reading event from the relay log
- 如果只是刚切完主库，但旧从库还没重连成功或位点未对齐，pt-table-checksum 会拒绝启动，这不是 bug，是保护机制
report_host 和 report_port 配置缺失导致从库发现失败
pt-table-checksum 默认用 processlist 或 hosts 方法自动发现从库，但前提是主库的 report_host 和 report_port 必须显式配置。若仍用默认值（空或 localhost），工具连到的可能是本机，而不是真实从库 IP。
- 检查命令：SELECT @@report_host, @@report_port;
- 若返回空或 127.0.0.1，需在主库配置文件中补全：
report_host = 192.168.10.100report_port = 3306
- 修改后无需重启，执行 SET GLOBAL report_host = '192.168.10.100'; 即可临时生效（但建议配死在 my.cnf）
从库权限不足或 bind_address 拦截远程连接
pt-table-checksum 会在主库发起连接，然后让从库自己连回主库执行 checksum 计算（反向连接）。如果从库：
- bind_address = 127.0.0.1，则无法接受来自主库的连接请求
- 校验用户（如 chkuser）没在从库上创建，或缺少 REPLICATION CLIENT + SELECT 权限
- 防火墙或安全组未放行从库到主库的出向 3306 端口
都会导致连接超时或 Access denied 报错，且错误日志常藏在从库 error log 里，主库侧只显示 “connection refused”
--no-check-binlog-format 忘加导致 ROW 模式下直接退出
MySQL 5.7+ 默认 binlog_format = ROW，而 pt-table-checksum 默认会检查该参数是否兼容（它要求 binlog_format = STATEMENT 才敢放心跑）。但现实中没人会为校验改主库 binlog 格式。
- 必须显式加 --no-check-binlog-format 参数，否则工具启动即报：
FATAL Error: Binary logging is not set to STATEMENT
- 这个参数不是“跳过检查”，而是告诉工具：“我知道是 ROW，别拦我，我保证表有主键/唯一索引，checksum 逻辑安全”
真正容易被忽略的，是 pt-table-checksum 并不校验“切换动作是否干净”，它只信任你给它的那个“当前主库”和“当前从库”状态。如果位点没对齐、GTID purged 错乱、或者从库还在执行旧 relay log，工具要么报错退出，要么给出错误的 checksum 结果——它不会主动帮你诊断这些底层问题。
