pt-replica-restart

监视一个或多个 MySQL 复制副本（replica），出错时跳过引起错误的语句并重启复制。

语法

pt-replica-restart [OPTIONS] [DSN]

用法示例

以下命令假定已通过选项文件或本机 socket 配置好 MySQL 连接；副本主机用 DSN（如 h=副本主机，不写明文密码）指定。本工具会跳过复制错误并重启线程，可能加剧主从数据不一致，使用前务必先排查错误根因——它用于"越过"错误而非"修复"复制。

场景：后台常驻自动重启

守护进程持续监视 replica-host，遇到可跳过的错误就自动重启复制线程：

pt-replica-restart --daemonize h=replica-host

场景：只跳过指定错误号

只处理重复主键（1062）这类已知无害错误，遇到列表外的错误直接退出，避免盲目跳过其它问题：

pt-replica-restart --error-numbers 1062 h=replica-host

场景：按错误文本匹配跳过

用 Perl 正则匹配 last_error 文本，只重启文本命中的错误：

pt-replica-restart --error-text 'Could not parse' h=replica-host

场景：追到指定 binlog 位点就停

让副本一直追到源的 mysql-bin.000123,456789 这个坐标为止再停，常用于把副本恢复到某个已知正确位点（格式 file,pos，逗号无空格）：

pt-replica-restart --until-source mysql-bin.000123,456789 h=replica-host

场景：顺带监视下级副本

主副本下面还有更深的从库时，用 --recurse 2 把下级副本也一并纳入监视（深度 2），多于一个时并行 fork 监视：

pt-replica-restart --recurse 2 h=replica-host

场景：靠 cron 每小时自愈重启

放进 crontab 每小时跑一次，用非默认 --sentinel 保证只停掉同一 cron 启动的实例，防服务器崩溃后漏重启：

pt-replica-restart --monitor --stop --sentinel /tmp/pt-replica-restartup h=replica-host

功能说明

监视一个或多个复制副本并尝试跳过导致错误的语句。以指数变化的睡眠时间智能轮询副本； 可以指定要跳过的错误，也可以让副本运行到某个 binlog 位置为止。

注意

该工具能帮副本越过错误继续复制，但不应依赖它来"修复"复制。 如果副本错误频繁或意外出现，应找出并修复根本原因。

输出

每次发现副本出错就打印一行：默认含时间戳、连接信息、relay_log_file、relay_log_pos、last_errno。 --verbose 可增加更多信息；--quiet 抑制全部输出。

睡眠策略（SLEEP）

• 初始睡眠时间为 --sleep。
• 检查发现错误时，睡眠时间减半；无错误时加倍。
• 睡眠时间下界为 --min-sleep，上界为 --max-sleep。
• 刚发现错误后，工具假设下一个错误很可能马上出现，因此睡"当前睡眠时间与初始睡眠时间的较小者"。

全局事务 ID（GTID）

自 Percona Toolkit 2.2.8 起支持 MySQL 5.6.5 引入的 GTID。注意：

• 使用多复制线程（replica_parallel_workers > 0）时不会跳过事务： 工具无法知道某个复制线程失败事务的 GTID 事件。
• 默认跳过来自副本源（source）的下一个事务；写入可能来自不同服务器（各自 UUID），见 --source-uuid。

退出状态与兼容性

0 表示成功；其他值为 Perl 进程（或多个被监控服务器时最后退出的 fork 进程）的退出状态。 SHOW REPLICA STATUS 输出列的大小写随版本变化，工具统一按小写处理。

选项

选项	说明
--always	即使没有错误也启动副本（开启后工具不会允许你手动停止副本！）
--ask-pass	连接 MySQL 时交互式询问密码
--[no]buffer-stdout	默认开启 STDOUT 缓冲；使用 tee、kubectl logs 等后处理工具想看到实时进度时可关闭
-A, --charset	类型：string。默认字符集（utf8 时设置 binmode/mysql_enable_utf8 并执行 SET NAMES UTF8）
--[no]check-relay-log	默认：yes。检查副本错误前先检查 relay log 文件与位置是否变化；未变化则仅睡眠，防止无限循环（同一位置反复重启同一错误）。某些错误需要 --no-check-relay-log 禁用该检查——除非清楚后果否则不要用
--config	类型：Array。读取逗号分隔的配置文件列表；如指定必须放在命令行第一个选项的位置
--daemonize	fork 到后台并与 shell 脱离，仅限 POSIX 系统
-D, --database	类型：string。使用的数据库
-F, --defaults-file	类型：string。只从给定文件读取 mysql 选项，必须给绝对路径
--error-length	类型：int。打印错误信息的最大长度（--verbose 足够高时截断错误文本，防止终端换行）
--error-numbers	类型：hash。只重启该错误号列表（逗号分隔）中的错误；遇到不在列表中的错误则退出。错误号取自 SHOW REPLICA STATUS 的 last_errno
--error-text	类型：string。只重启错误文本匹配该 Perl 正则的错误；存在但不匹配则退出。错误文本取自 last_error 列
--help	显示帮助并退出
-h, --host	类型：string。要连接的主机
--log	类型：string。daemonize 时把全部输出打印到该文件
--master-uuid	已废弃，用 --source-uuid 代替
--max-sleep	类型：float；默认：64。轮询间隔的睡眠上限秒数；也是 --stop + --monitor 时等待其他实例退出的时长
--min-sleep	类型：float；默认：0.015625。轮询间隔的睡眠下限秒数
--monitor	是否监视副本（默认）。未显式指定时 --stop 会禁用它
-s, --mysql_ssl	类型：int。创建 SSL MySQL 连接
-p, --password	类型：string。连接密码（含逗号需转义）
--pid	类型：string。创建指定的 PID 文件；冲突规则与自动清理见官方文档
-P, --port	类型：int。连接端口
-q, --quiet	抑制常规输出（并禁用 --verbose）
--recurse	类型：int；默认：0。同时监视指定服务器的下级副本至该层级深度。通过 SHOW PROCESSLIST 识别副本连接后接入；程序启动时找出全部副本并监视，多于一个时用 fork() 并行监视。副本配置了 report_host 等 report 参数时也可通过 SHOW REPLICAS 发现
--recursion-method	类型：array；默认：processlist,hosts。查找副本的方法：processlist（SHOW PROCESSLIST，首选）、hosts（SHOW REPLICAS，MySQL 8.1 前为 SHOW SLAVE HOSTS，非标准端口时必需）、none。首选方法找不到时会尝试其他方法
--run-time	类型：time。运行多久后退出（后缀 s/m/h/d，缺省 s）
--sentinel	类型：string；默认：/tmp/pt-replica-restart-sentinel。该文件存在时退出
--slave-user	已废弃，用 --replica-user 代替
--slave-password	已废弃，用 --replica-password 代替
--replica-user	类型：string。连接副本使用的用户（可在副本上用权限更低的用户，但须存在于所有副本上）
--replica-password	类型：string。连接副本使用的密码（与 --replica-user 配合，所有副本上须一致）
--set-vars	类型：Array。以逗号分隔的 变量=值 列表设置 MySQL 变量；默认 wait_timeout=10000；无法设置时打印警告并继续
--skip-count	类型：int；默认：1。重启副本时跳过的语句数
--source-uuid	类型：string。GTID 模式下跳过事务需要创建空事务；写入来自多个节点时需指定要跳过哪个 UUID 的事件。默认跳过副本源（SHOW REPLICA STATUS 的 Source_UUID）的事务。例：source1 -> replica1 -> replica2，在 replica2 上跳过 source1 写入的事件时必须指定 source1 的 UUID，否则默认用 replica1 的 UUID
--sleep	类型：int；默认：1。检查副本之间的初始睡眠秒数
-S, --socket	类型：string。连接使用的 socket 文件
--stop	创建 sentinel 文件以停止运行中的实例：停止所有监视同一 sentinel 文件的实例。未指定 --monitor 时创建后即退出；指定时等待 --max-sleep 后删除文件继续工作。可用来优雅停止 cron 任务或替换运行实例（官方文档有每小时重启的 crontab 示例）
--until-master	已废弃，用 --until-source 代替
--until-source	类型：string。运行到源的该 binlog 文件与位置为止，格式 file,pos（逗号分隔，无空格）；坐标取 relay_source_log_file/exec_source_log_pos。会给 START REPLICA 加 UNTIL 子句；到达后副本停止、工具退出
--until-relay	类型：string。运行到中继日志的该文件与位置为止（坐标取 relay_log_file/relay_log_pos）
-u, --user	类型：string。登录用户（若非当前用户）
-v, --verbose	累积选项，默认 1 级：-v 增加 last_error；-vv 每次睡眠时打印当前睡眠时间
--version	显示版本并退出
--[no]version-check	默认：yes。检查 Percona Toolkit、MySQL 等软件的最新版本与已知问题版本（详见版本检查）

DSN 选项

键	DSN 部分	说明
A	charset	默认字符集
D	database	默认数据库
F	mysql_read_default_file	只从给定文件读取默认选项
h	host	要连接的主机
p	password	连接密码（含逗号需转义）
P	port	连接端口
S	mysql_socket	连接使用的 socket 文件
u	user	登录用户（若非当前用户）
s	mysql_ssl	创建 SSL 连接

其他信息

• 作者：Baron Schwartz

• 通用说明：已知问题的反馈方式、PTDEBUG 调试安全提示、系统要求基线，见 通用说明。

更多细节请阅读 官方文档。