Vitess v18.0.4 补丁版本解析:VReplication 工作流修复、查询构建器回归与构建链升级
Vitess v18.0.4 补丁版本解析:VReplication 工作流修复、查询构建器回归与构建链升级
导读
v18.0.4 是 Vitess 18.0 系列中的一个补丁(patch)版本,它的职责不是引入新特性,而是针对 VReplication 工作流管理与查询规划两个关键路径做定向修复,并同步升级构建工具链与依赖。本文以官方 changelog 为骨架,结合仓库源码逐条还原每个修复背后的实现原理,帮助你理解:工作流更新时"变更判定"如何被修正、跨 keyspace 查询构建中 keyspace 前缀如何被错误保留、读流量切换(SwitchReads)的测试为何整体迁往 vtctldclient,以及这些修复对你的生产升级意味着什么。
一、版本定位:v18.0.4 在 18.0 发布节奏中的角色
从 changelog 的 Release 一节可以看到:
- [release-18.0] Bump to
v18.0.4-SNAPSHOTafter thev18.0.3release #15489
这行记录说明 v18.0.4 的版本号是在 v18.0.3 发布之后,由 release-18.0 分支直接以 v18.0.4-SNAPSHOT 的名义继续推进的。也就是说,该版本不经过主线(main)的功能开发周期,而是从已发布的 18.0 系列中直接派生的小版本,其提交全部带有 [release-18.0] 前缀,属于典型的"只修复、不添功能"的维护节奏。
本次变更一共覆盖四个类别:
| 类别 | 数量 | 涉及模块 |
|---|---|---|
| Bug fixes | 1 | VReplication |
| CI/Build | 3 | Build/CI、General(Go 版本与依赖升级) |
| Regression | 1 | Query Serving(查询构建器) |
| Testing | 1 | VReplication(e2e 测试迁移) |
二、核心 Bug 修复:VReplication 工作流更新"变更判定"修正
- [release-18.0] VReplication: Fix workflow update changed handling (#15621) #15628
VReplication 是 Vitess 中所有移动数据类工作流(MoveTables、Reshard、Migrate 等)的底层引擎。vtctldclient workflow update(对应 gRPC 接口 WorkflowUpdate)允许运维人员在运行时修改某个 VReplication 工作流的参数,例如暂停/恢复复制(state)、调整单元格(cells)、变更 tablet 类型(tablet_types)或 DDL 处理策略(on_ddl)。
在服务端,该请求由 go/vt/vtctl/workflow/server.go 中的 WorkflowUpdate 方法实现,其核心流程是:
- 构造一个
vexec.NewVExec(keyspace, workflow, ...)执行器; - 通过
s.tmc.UpdateVReplicationWorkflow把WorkflowUpdateRequest中内嵌的TabletRequest下发到参与该工作流的目标主副本(target primary tablets); - 汇总每个 tablet 返回的
RowsAffected,RowsAffected > 0即认为该 tablet 上的工作流确实发生了变更,并写入响应的Details中。
这次修复针对的正是"changed(变更)判定"逻辑(PR #15621)。在 UpdateVReplicationWorkflow 的实现中,对每个 tablet 执行的是 update _vt.vreplication set ... where db_name=... and workflow=... 类型的 SQL(可参见 server.go 中的 SqlUnfreezeWorkflow 等语句模板)。如果待更新字段的值与当前值完全相同,MySQL 的 UPDATE 不会产生实际变更,RowsAffected 返回 0——旧版本中这会导致客户端收到"未更新"的错误信号,即使请求本身是合法的(例如重复提交相同配置)。修复后,系统会正确地区分"字段值本就一致(无需变更)"与"工作流/keyspace 不存在(真正失败)"两种情况,后者仍会返回 FAILED_PRECONDITION 错误:
if len(res) == 0 {
return nil, vterrors.Errorf(vtrpcpb.Code_FAILED_PRECONDITION,
"the %s workflow does not exist in the %s keyspace", ...)
}
升级意义:如果你在自动化脚本中反复调用 vtctldclient workflow update(例如幂等地把 on_ddl 或 cells 设置为目标值),旧版本可能出现误报失败或状态不一致,v18.0.4 之后该路径的行为更稳定、更可预期。
三、查询服务回归修复:查询构建器误保留 keyspace 列前缀
- [release-18.0] fix: remove keyspace from column during query builder (#15514) #15516
这条回归修复位于 Query Serving / 查询规划(planning) 链路。它影响的是 VTGate 执行单 keyspace、无分片(unsharded)短路查询时的语句改写。
在 VTGate 的规划器中,当一次查询的所有表都落在同一个未分片 keyspace 内时,会走"未分片快捷路径"(unsharded shortcut),把查询中表名和列名上的 keyspace 限定符去掉后再下推给 MySQL,避免把 ks1.t1 这类限定符原样透传到 MySQL 导致语法错误。该逻辑位于 go/vt/vtgate/planbuilder/single_sharded_shortcut.go:
sqlparser.SafeRewrite(stmt, nil, func(cursor *sqlparser.Cursor) bool {
switch node := cursor.Node().(type) {
case sqlparser.SelectExpr:
removeKeyspaceFromSelectExpr(node)
case sqlparser.TableName:
cursor.Replace(sqlparser.TableName{Name: node.Name})
}
return true
})
而 removeKeyspaceFromSelectExpr(single_sharded_shortcut.go)对两类投影项分别处理:
*sqlparser.AliasedExpr:调用sqlparser.RemoveKeyspaceInCol(expr.Expr)剥掉表达式内列的 keyspace 限定符;*sqlparser.StarExpr:把*前的表限定符清空为""。
本次回归(#15514)所修复的场景,正是该链路中某些列表达式(column expression)上的 keyspace 前缀没有被完整剥离的边界情况,导致下推 SQL 形如 select ks.t.c from ... 而执行失败。同目录的规划器测试数据(如 go/vt/vtgate/planbuilder/testdata/select_cases.json)覆盖了大量此类查询规划案例,是验证该行为的主要手段。
升级意义:如果你在未分片 keyspace 上大量使用带 keyspace 限定符的 SELECT(例如 select ks.orders.id from ks.orders),v18.0.4 能修复这类语句偶发规划失败的问题;对分片 keyspace 与跨 keyspace 查询没有行为变化。
四、测试加固:SwitchReads 相关修复与 e2e 测试迁移
- [release-18.0] VReplication: Fix vtctldclient SwitchReads related bugs and move the TestBasicV2Workflows e2e test to vtctldclient (#15579) #15583
SwitchReads 是移动数据工作流中"切换读流量"的关键一步:把 REPLICA / RDONLY 的读流量从源 shard 平滑切到目标 shard。其核心实现位于 go/vt/wrangler/traffic_switcher.go 的 Wrangler.SwitchReads 方法,包含几类值得注意的防御逻辑:
- 方向校验:反向(backward)切换时,若 REPLICA 或 RDONLY 的读流量从未被切换过,直接报错拒绝(traffic_switcher.go);
- tablet 类型校验:只接受
REPLICA与RDONLY两种类型(traffic_switcher.go); - RDONLY 自动补全:如果当前 cell 中不存在任何 RDONLY tablet,会自动把
RDONLY追加进待切换类型,避免因"无 RDONLY 可切"导致工作流永远无法标记完成(traffic_switcher.go); - journal 检查:切换前检查源 keyspace 是否残留上一次迁移的 journal 记录;
- 加锁:读切换只需要锁源 keyspace(
lockKeyspace(ts.SourceKeyspaceName(), "SwitchReads"))。
PR #15579 修复的是 vtctldclient(go/cmd/vtctldclient 下对应的 workflow switchreads 子命令)在驱动这套切换流程时的若干 bug,同时把 TestBasicV2Workflows 这个端到端(e2e)测试从旧的 vtctl 客户端迁移到了 vtctldclient。这是一项重要的测试策略变更:随着 Vitess 逐步以 vtctldclient 取代遗留 vtctl 命令,e2e 测试必须覆盖新客户端路径,才能保证工作流管理类功能在被真实使用时是可靠的。
升级意义:使用 vtctldclient workflow switchreads 做读流量切换(例如 examples/local/203_switch_reads.sh 演示的流程)的用户,升级后能获得更稳定的命令行为,同时该路径的 e2e 覆盖也更充分。
五、构建链与依赖升级:工具链现代化
v18.0.4 还包含三项不直接改功能、但影响发布质量与安全性的构建变更:
| PR | 内容 | 影响 |
|---|---|---|
| #15533 | 更新到最新 CodeQL | 代码扫描规则同步到最新,提升供应链安全审计覆盖 |
| #15646 / #15639 | go.mod 与 CI 中 Go 版本升级到 1.21.9 | 修复工具链已知问题,确保 release-18.0 分支使用受支持的 Go 版本编译 |
| #15650 | 升级 golang.org/x/net |
拉取该依赖链的安全/兼容性修复 |
需要说明的是:当前仓库主干的 go.mod 已声明 go 1.27.1,而 v18.0.4 属于 release-18.0 维护分支,其构建基线是 go1.21.9。两者不矛盾——补丁版本只在其分支对应的 Go 版本上构建与发布,升级到 v18.0.4 时请使用与发布流程一致的 Go 工具链。
六、升级建议与验证清单
v18.0.4 不引入破坏性变更,属于可平滑升级的补丁版本。升级后可重点验证以下行为是否恢复正常:
- 工作流更新幂等性:对同一 MoveTables/Reshard 工作流连续执行两次
vtctldclient workflow update,第二次不应再出现误报"未变更"或状态混乱; - 未分片 keyspace 限定查询:执行
select <ks>.<table>.<col> from <ks>.<table>形式的 SELECT,确认查询构建器正确剥离 keyspace 前缀并可正常返回; - 读流量切换:按 examples/local/203_switch_reads.sh 的流程执行
vtctldclient workflow switchreads,确认 REPLICA/RDONLY 切换、dry-run 与反向切换均正常,且 e2e 测试TestBasicV2Workflows在 vtctldclient 路径下全绿; - 构建环境:CI 使用 go1.21.9 重新编译,确认无工具链告警。
小结
v18.0.4 是一个小而精的维护版本:一条 VReplication 工作流更新的"变更判定"修复(server.go)、一条查询构建器的 keyspace 前缀回归修复(single_sharded_shortcut.go)、一条 SwitchReads 的客户端修复加 e2e 迁移(traffic_switcher.go),外加 CodeQL、Go 1.21.9 与 golang.org/x/net 的例行升级。对于运行 18.0 系列并重度使用 VReplication 工作流与跨 keyspace 查询的集群,这是一个成本低、收益明确的升级目标。