MySQL WAIT_FOR_EXECUTED_GTID_SET 怎样等待复制位点追平

我在做 MySQL 读流量切换时，最容易误判的不是“副本有没有延迟”，而是“副本是否已经执行了这一次切换真正关心的事务”。这时不要只盯着 Seconds_Behind_Source，而应把源端产生的 GTID 集合交给副本执行 WAIT_FOR_EXECUTED_GTID_SET()。

官方资料：https://dev.mysql.com/doc/refman/8.4/en/replication-functions.html

先把“复制延迟”换成一个明确的 GTID 目标

我通常先在源端记录本次切换边界，再把这个集合传给准备接管读流量的副本。目标可以来自提交事务后观察到的 GTID 集合，也可以来自发布流程已经保存的位点。关键是：目标必须是一个带引号的 GTID 集合字符串，不能把模糊的“尽量追平”交给等待函数。

-- 在源端读取本次切换需要等待的 GTID 集合。
SELECT @@GLOBAL.gtid_executed AS source_executed;

-- 在副本上查看当前已经执行到哪里，用于记录等待前的起点。
SELECT @@GLOBAL.gtid_executed AS replica_before;

例如源端得到的目标是 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-125，它表达的是一个集合，而不是单个自增数字。副本只需要确认自己的 gtid_executed 已经包含这个集合。

用超时等待目标集合，并按返回值做决定

函数的第二个参数是等待秒数。实际切换时我更倾向于显式写出超时，而不是使用默认的无限等待；这样自动化流程能把“暂时没有追平”交给上层处理。下面的查询只返回状态，不把超时误当成 SQL 执行失败。

-- 在副本连接上等待目标集合，最多等待 30 秒。
SELECT WAIT_FOR_EXECUTED_GTID_SET(
    '3E11FA47-71CA-11E1-9E33-C80AA9429562:1-125',
    30
) AS wait_result;

返回值要按三类理解：0 是目标集合已经满足；1 是等待达到上限仍未满足；其他异常通常意味着参数或执行条件有问题。返回 1 时不要直接宣布副本不可用，先记录当前集合并检查复制线程、网络和事务冲突，再决定重试还是取消切换。

等待函数观察的是执行集合，不是某一条通道

这个边界是我第一次接入自动切换时最容易漏掉的地方。官方定义是：函数检查当前服务器已经应用的事务，包含来自不同复制通道和用户客户端的事务；它不会替你判断某条复制通道是启动还是停止。因此，函数返回 0 只能说明目标 GTID 已被当前服务器执行，不能单独证明拓扑健康。

-- 等待成功后，再把 GTID 集合和复制状态一起记录。
SELECT @@GLOBAL.gtid_executed AS replica_executed;

-- 查看副本复制线程的现场状态；这里只用于补充判断。
SHOW REPLICA STATUS;

如果系统有多个 channel，还要明确目标 GTID 是否可能来自其他 channel 或本地客户端。切换门禁可以把“目标集合已满足”作为必要条件，但仍应把复制线程状态、错误计数和业务健康检查作为并列条件。

超时、负数和切换前的三个检查点

我会把下面三点写进切换脚本的日志，而不是只保留一个布尔值：

• 目标是否固定：每次等待记录目标 GTID 和副本连接，避免源端目标变化后继续等待旧集合。
• 超时是否可解释：返回 1 后保存当前 gtid_executed，再结合 SHOW REPLICA STATUS 判断是网络、SQL 执行还是锁冲突。
• 参数是否有效：超时必须大于或等于零；负数不是“立刻返回”的通用写法，严格 SQL 模式下会被拒绝，非严格模式也可能返回 NULL 并产生警告。

如果希望一直等到追平，可以省略超时参数，但生产切换通常更需要可控的上限。对我来说，最稳妥的组合是“显式 GTID 目标 + 有限等待 + 返回值分支 + 复制状态补充检查”，而不是把某个延迟秒数当成唯一依据。

常见问题

WAIT_FOR_EXECUTED_GTID_SET 返回 1 是不是 SQL 失败？

不是。返回 1 表示等待超时，SQL 本身完成了等待动作；应读取当前执行集合并检查复制现场。

能不能用它确认某个复制 channel 正常？

不能单独确认。函数关注当前服务器是否执行了目标 GTID，通道启停和复制健康仍要结合 SHOW REPLICA STATUS 等信息判断。

为什么不能把超时写成负数表示不等待？

负数属于参数边界，不是稳定的“不等待”语义；严格模式会报错，其他模式可能得到 NULL 和警告。需要有限等待时使用非负秒数。