发布日期: 2025-11-04
版本号: v23.0.0

Vitess v23.0.0版本发布,包含246个合并的Pull Request。主要变更如下:

重大变更:

  1. 破坏性变更:移除了四个已在v22.0.0废弃的VTGate指标(QueriesProcessed等),需迁移到新指标。ExecuteFetchAsDba方法不再接受多语句SQL。gRPC TabletManager错误码改用vterrors.Code()检查。部分GTID和分片范围API签名更新。
  2. CLI标志命名迁移:989个标志从下划线格式(如--flag_name)迁移到连字符格式(如--flag-name)。v23/v24版本兼容两种格式,但下划线格式已废弃,v25版本将移除。
  3. 默认MySQL版本升级:从MySQL 8.0.40升至8.4.6。使用vitess-operator升级时需按步骤操作。
  4. 新功能支持
    • 多查询执行(通过ExecuteMulti API)
    • 会话级事务超时控制(transaction_timeout变量)
    • 实验性查询限流器(Query Throttler)
    • 工作流中支持多个Lookup Vindex
    • 可向物化工作流添加引用表
    • Online DDL支持按分片完成迁移
    • 支持WITH RECURSIVE递归CTE和CREATE TABLE ... SELECT语句
  5. 废弃与删除:废弃DiscoverInstanceTimings指标;废弃989个CLI标志的下划线格式;删除四个VTGate指标。
  6. 新指标:VTGate新增TransactionsProcessed(按分片和类型统计)等指标;VTOrc新增SkippedRecoveries(带原因追踪)等指标。

次要变更:

  • 新增多个CLI标志,包括VReplication的--params-file、可观测性的--skip-user-metrics、VTOrc的--allow-recovery等。
  • VTOrc恢复指标新增KeyspaceShard标签;VTGate的QueryExecutionsByTable仅统计成功查询。
  • SQL解析器增强:支持更多语法,改进CREATE PROCEDURE解析,修复运算符优先级。
  • 查询规划改进:窗口函数可下推到单分片查询;优化UNION查询合并;单分片模式下只读事务可跨分片。
  • 拓扑:--consul-auth-static-file需至少1个凭证。
  • VTOrc:移除聚合发现指标API;支持动态控制EmergencyReparentShard恢复;废弃/api/replication-analysis端点。
  • VTTablet:新增RestartReplication等API;默认使用caching_sha2_password认证插件;修复MySQL时区环境变量传递问题。
  • Docker:不再构建基于Debian Bullseye的镜像。

升级前请详细查阅完整变更日志。感谢所有贡献者。

更新内容 (中文)

Vitess v23.0.0 发布说明

摘要

目录

主要变更

破坏性变更

删除的 VTGate 指标

四个已弃用的 VTGate 指标已在 v23.0.0 中完全移除。这些指标在 v22.0.0 中已弃用:

指标名称 组件 弃用版本
QueriesProcessed vtgate v22.0.0
QueriesRouted vtgate v22.0.0
QueriesProcessedByTable vtgate v22.0.0
QueriesRoutedByTable vtgate v22.0.0

影响:使用这些指标的监控仪表板或告警系统必须更新为使用 v22.0.0 中引入的替代指标:

  • 使用 QueryExecutions 代替 QueriesProcessed
  • 使用 QueryRoutes 代替 QueriesRouted
  • 使用 QueryExecutionsByTable 代替 QueriesProcessedByTableQueriesRoutedByTable

有关新指标的详细信息,请参阅 v22.0.0 发布说明

ExecuteFetchAsDba 不再接受多语句 SQL

TabletManager 中的 ExecuteFetchAsDba RPC 方法现在明确拒绝包含多个语句的 SQL 查询(参见 PR #18183)。

影响:之前向 ExecuteFetchAsDba 传递多个分号分隔的 SQL 语句的代码或自动化流程现在将收到错误。每个 SQL 语句必须通过单独的 RPC 调用发送。

迁移:将多语句 SQL 拆分为单独的 RPC 调用:

// 之前(不再有效):
ExecuteFetchAsDba("CREATE TABLE t1 (id INT); CREATE TABLE t2 (id INT);")

// 之后(v23+ 中必需):
ExecuteFetchAsDba("CREATE TABLE t1 (id INT);")
ExecuteFetchAsDba("CREATE TABLE t2 (id INT);")

gRPC TabletManager 错误代码变更

vttablet gRPC tabletmanager 客户端现在返回由内部 go/vt/vterrors 包包装的错误(PR #18565)。

影响:依赖 google-gRPC 错误代码的外部自动化必须更新为使用 vterrors.Code(err) 来检查错误代码,该方法返回在 proto/vtrpc.proto 中定义的 vtrpcpb.Code

迁移

// 之前:
if status.Code(err) == codes.NotFound { ... }

// 之后:
if vterrors.Code(err) == vtrpcpb.Code_NOT_FOUND { ... }

GTID API 签名变更

PR #18196 中,作为 GTID 性能优化的一部分,几个与 GTID 相关的 API 签名发生了变化:

变更BinlogEvent.GTID() 方法签名 影响:直接使用 GTID 解析 API 的代码可能需要更新。大多数用户不受影响,因为这些是内部 API。

GenerateShardRanges API 签名变更

key.GenerateShardRanges() 函数签名在 PR #18633 中发生了变化,增加了一个新的 hexChars int 参数来控制生成分片名称的十六进制宽度。

影响:直接调用 GenerateShardRanges() 的代码必须更新以传递新参数。

相应的 vtctldclient 命令增加了一个新的 --chars 标志来控制此行为。


CLI 标志命名规范迁移

Vitess v23.0.0 对所有二进制文件的 CLI 标志命名规范进行了重大标准化。在 PR #18280 及相关 PR 中,989 个标志已从下划线表示法(flag_name)迁移至破折号表示法(flag-name)。

向后兼容性

  • v23.0.0 和 v24.0.0:同时支持下划线和破折号格式。下划线格式已弃用但功能正常。
  • v25.0.0:将移除下划线格式。仅接受破折号格式。

自动规范化

标志规范化在 pflag 层级自动进行(PR #18642),因此在 v23/v24 中无需代码更改即可接受两种格式。

示例标志重命名

受影响的常用标志(完整 989 个标志列表请参见 PR #18280):

备份标志

  • --azblob_backup_account_name--azblob-backup-account-name
  • --s3_backup_storage_bucket--s3-backup-storage-bucket
  • --xtrabackup_root_path--xtrabackup-root-path

复制标志

  • --heartbeat_enable--heartbeat-enable
  • --replication_connect_retry--replication-connect-retry

gRPC 标志PR #18009):

  • 所有 gRPC 相关标志已标准化(30+ 个标志)

所需操作

用户应在升级至 v25.0.0 之前更新配置文件、脚本和自动化以使用基于破折号的标志名称。在 v23 和 v24 中迁移是向后兼容的,允许逐步更新。


新默认版本

升级至 MySQL 8.4

我们的 vitess/lite:latest 镜像使用的默认主 MySQL 版本从 8.0.40 升级至 8.4.6。 此更改已在 #18569 中合并。

VTGate 默认也广播 MySQL 版本 8.4.6 而非 8.0.40。如果您运行的不是此版本,可以设置 mysql_server_version 标志来广播所需的版本。

⚠️ 使用 vitess-operator 升级到此版本:

如果您使用 vitess-operator,考虑到我们将 MySQL 版本从 8.0.40 提升至 8.4.6,您将需要手动升级:

  1. 在 YAML 文件的 extra cnf 中添加 innodb_fast_shutdown=0
  2. 应用此文件。
  3. 等待所有 Pod 变为健康状态。
  4. 然后更改您的 YAML 文件以使用新的 Docker 镜像(vitess/lite:v23.0.0)。
  5. 从 YAML 文件的 extra cnf 中移除 innodb_fast_shutdown=0
  6. 应用此文件。

这仅在从最新的 8.0.x 升级至 8.4.x 时需要。一旦您处于 8.4.x,就可以在 8.4.x 版本之间升级和降级,而无需运行 innodb_fast_shutdown=0


新增支持

多查询执行

Vitess v23.0.0 引入了通过新的 ExecuteMultiStreamExecuteMulti API 在单个 RPC 调用中执行多个查询的原生支持(PR #18059)。

此功能提供了更高效的批量查询执行,无需手动拆分查询或多次往返。

使用示例

queries := []string{
    "SELECT * FROM users WHERE id = 1",
    "SELECT * FROM orders WHERE user_id = 1",
    "SELECT * FROM payments WHERE user_id = 1",
}
results, err := vtgateConn.ExecuteMulti(ctx, queries)

配置:通过 VTGate 上的 --mysql-server-multi-query-protocol 标志启用。

事务超时会话变量

新增了一个 transaction_timeout 会话变量(PR #18560),允许按会话控制事务超时持续时间。

用法

-- 将此会话的事务超时设置为 30 秒
SET transaction_timeout = 30;

-- 开始一个事务,如果在 30 秒内未提交将自动回滚
BEGIN;
-- ... 执行操作 ...
COMMIT;

与全局服务器设置相比,这提供了更精细的超时控制,适用于:

  • 需要延长超时的长时间运行批处理操作
  • 应该快速失败的交互式会话
  • 每个应用程序工作负载不同的超时要求

实验性:查询限流器

Vitess v23.0.0 引入了一个新的实验性查询限流器框架,用于对传入查询进行速率限制(RFC issue #18412PR #18449PR #18657)。此新限流器的工作正在进行中,未来可能会有破坏性变更。

感谢在 GitHub issues 或 Vitess Community Slack#feat-handling-overload 频道提供有关此实验性功能的反馈。

功能

  • 基于文件的限流规则配置
  • 用于测试限流而不强制执行的试运行模式
  • 动态规则重载

配置

  • --query-throttler-config-refresh-interval - 多久重新加载一次限流器配置

试运行模式:测试限流规则而不实际阻止查询,用于在强制执行前验证配置。

多查找 VIndex 支持

现在可以通过 --params-file 标志在单个工作流中创建多个查找 VIndex(PR #17566)。

用法

# 从 JSON 配置创建多个查找 VIndex
vtctldclient LookupVindexCreate \
  --workflow my_lookup_workflow \
  --params-file /path/to/params.json \
  commerce

params.json 示例

{
  "vindexes": [
    {
      "name": "user_email_lookup",
      "type": "consistent_lookup_unique",
      "table_owner": "users",
      "table_owner_columns": ["email"]
    },
    {
      "name": "user_name_lookup",
      "type": "consistent_lookup",
      "table_owner": "users",
      "table_owner_columns": ["name"]
    }
  ]
}

这显著提高了设置多个 VIndex 时的工作流效率,减少了所需的单独操作数量。

物化工作流中的引用表

现在可以使用新的 Materialize ... update 子命令将引用表添加到现有的物化工作流中(PR #17804)。

用法

# 将引用表添加到现有工作流
vtctldclient Materialize --workflow my_workflow update \
  --add-reference-tables ref_table1,ref_table2 \
  --target-keyspace my_keyspace

用例:无需重新创建整个工作流即可将引用表增量添加到运行的物化工作流中,提高了操作灵活性。

Online DDL 分片级别完成

Online DDL 迁移现在可以使用新的 COMPLETE VITESS_SHARDS 语法按分片完成(PR #18331)。

用法

-- 仅在特定分片上完成迁移
ALTER VITESS_MIGRATION '9e8a9249_3976_11ed_9442_0a43f95f28a3'
  COMPLETE VITESS_SHARDS '-80,80-';

-- 在所有剩余分片上完成迁移
ALTER VITESS_MIGRATION '9e8a9249_3976_11ed_9442_0a43f95f28a3'
  COMPLETE;

优点

  • 跨分片逐步部署模式更改
  • 能够在完整部署前在分片子集上验证更改
  • 更好地控制迁移时间和影响

WITH RECURSIVE CTEs

Vitess 现在支持 WITH RECURSIVE 公共表表达式(PR #18590),为层级数据启用递归查询。

示例

-- 查找管理层级中的所有员工
WITH RECURSIVE employee_hierarchy AS (
    SELECT id, name, manager_id, 1 as level
    FROM employees
    WHERE manager_id IS NULL

    UNION ALL

    SELECT e.id, e.name, e.manager_id, eh.level + 1
    FROM employees e
    INNER JOIN employee_hierarchy eh ON e.manager_id = eh.id
)
SELECT * FROM employee_hierarchy ORDER BY level, name;

这是对具有分层或图形状数据结构的应用程序的重大 SQL 兼容性增强。

CREATE TABLE … SELECT 支持

SQL 解析器现在支持 CREATE TABLE ... SELECT 语句(PR #18443),提高了 MySQL 兼容性。

示例

-- 根据查询结果创建表
CREATE TABLE recent_orders
SELECT * FROM orders
WHERE order_date > DATE_SUB(NOW(), INTERVAL 30 DAY);

弃用

指标

组件 指标名称 备注 弃用 PR
vtorc DiscoverInstanceTimings 已由 DiscoveryInstanceTimings 替代 #18406

CLI 标志

作为 CLI 标志命名规范迁移 的一部分,989 个 CLI 标志在所有 Vitess 二进制文件中已弃用其下划线格式。未来应使用破折号格式。

弃用时间线

  • v23.0.0 和 v24.0.0:下划线格式已弃用但功能正常
  • v25.0.0:将移除下划线格式

所需操作:在 v25.0.0 之前迁移到基于破折号的标志名称。详情请参阅 CLI 标志命名规范迁移


删除

指标

组件 指标名称 弃用版本 弃用 PR
vtgate QueriesProcessed v22.0.0 #17727
vtgate QueriesRouted v22.0.0 #17727
vtgate QueriesProcessedByTable v22.0.0 #17727
vtgate QueriesRoutedByTable v22.0.0 #17727

迁移指南请参阅 破坏性变更


新增指标

VTGate

名称 维度 描述 PR
TransactionsProcessed Shard, Type 统计在 VTGate 处理的事务,按分片分布和事务类型划分。 #18171
OptimizedQueryExecutions 跟踪使用延迟优化执行路径的查询的计数器。 #18067

TransactionsProcessed 中的事务类型

  • Single - 单分片事务
  • Multi - 多分片事务
  • TwoPC - 两阶段提交事务

用例TransactionsProcessed 指标有助于识别事务模式和分片分布,可用于:

  • 监控部署中的事务类型
  • 识别可以优化为单分片的查询
  • 跟踪两阶段提交使用情况和潜在瓶颈

VTTablet

名称 维度 描述 PR
OnlineDDLStaleMigrationMinutes 自提交最旧的待处理/就绪迁移以来经过的分钟数。 #18417
vttablet_tablet_server_state type, keyspace, shard 增加了额外的维度以提供更好的可观测性。 #18451

OnlineDDLStaleMigrationMinutes 的用例:对长时间未进展的停滞 Online DDL 迁移发出警报,帮助识别可能需要干预的迁移。

VTOrc

名称 维度 描述 PR
SkippedRecoveries RecoveryName, Keyspace, Shard, Reason 跳过的恢复计数及原因跟踪。 #18644
EmergencyReparentShardDisabled Keyspace, Shard 指示 ERS 是否按 keyspace/shard 禁用的仪表。 #17985

EmergencyReparentShardDisabled 的用例:创建警报以确保 EmergencyReparentShard 恢复不会在不需要的时间段内被禁用,保持高可用性状态。

SkippedRecoveries 原因Reason 维度跟踪恢复被跳过的原因(例如 “ERSDisabled”、“ReplicationLagHigh”、“NotEnoughReplicas”),为操作故障排除提供可操作的见解。


次要变更

新增 CLI 标志

VReplication/物化

标志 组件 描述 PR
--params-file vtctldclient 包含查找 VIndex 参数的 JSON 文件,用于在单个工作流中创建多个查找 VIndex。与 --type--table-owner--table-owner-columns 互斥。 #17566
--add-reference-tables vtctldclient 逗号分隔的引用表列表,用于使用 update 子命令添加到现有的物化工作流。 #17804

可观测性

标志 组件 描述 PR
--skip-user-metrics vttablet 如果启用,将用户指标中的用户名标签替换为 “UserLabelDisabled”,以防止在具有许多唯一用户的环境中出现指标基数爆炸。 #18085
--querylog-emit-on-any-condition-met vtgate, vttablet, vtcombo 更改查询日志发送行为,在满足任何日志条件(行阈值、时间阈值、过滤器标签或错误)时发送,而不是要求满足所有条件。默认:false。 #18546
--querylog-time-threshold vtgate, vttablet 查询日志记录的持续时间阈值。超过此持续时间的查询将被记录。与 --querylog-emit-on-any-condition-met 一起使用。 #18520
--grpc-enable-orca-metrics vtgate, vttablet 启用通过 gRPC 报告 ORCA(开放请求成本聚合)后端指标以用于负载均衡决策。默认:false。 #18282
--datadog-trace-debug-mode 所有组件 使 Datadog 追踪调试模式可配置,而非始终开启。默认:false。 #18347

VTOrc

标志 组件 描述 PR
--allow-recovery vtorc 布尔标志,用于在启动时禁用所有 VTOrc 恢复操作。为 false 时,VTOrc 仅以监控模式运行。默认:true。 #18005

用例--allow-recovery=false 标志适用于:

  • 在部署前测试 VTOrc 能力/发现性能,例如:从另一个解决方案迁移到 VTOrc。
  • 应防止自动故障转移的维护窗口
  • 调试 VTOrc 行为而不触发恢复
  • 以仅观察模式运行 VTOrc

备份/恢复

标志 组件 描述 PR
--xtrabackup-should-drain vttablet 使 ShouldDrainForBackup 行为对 xtrabackup 引擎可配置。为 true 时,tablet 在备份前排空流量。默认:true。 #18431

CLI 工具

标志 组件 描述 PR
--chars vtctldclient 指定使用 GenerateShardRanges 命令生成分片范围时使用的十六进制宽度(十六进制字符数)。允许对分片命名进行细粒度控制。 #18633

示例

# 生成具有 4 个十六进制字符的分片范围
vtctldclient GenerateShardRanges --shards 16 --chars 4
# 输出:-1000,1000-2000,2000-3000,...,f000-

VTAdmin

为安全的 vtctld 连接添加了五个与 TLS 相关的新标志(PR #18556):

标志 描述
--vtctld-grpc-ca vtctld gRPC TLS 的 CA 证书文件
--vtctld-grpc-cert vtctld gRPC TLS 的客户端证书文件
--vtctld-grpc-key vtctld gRPC TLS 的客户端密钥文件
--vtctld-grpc-server-name 用于 vtctld gRPC TLS 验证的服务器名称
--vtctld-grpc-crl vtctld gRPC TLS 的证书吊销列表

这些标志支持 VTAdmin 和 vtctld 之间的 mTLS(双向 TLS)身份验证以增强安全性。

VTGate

标志 组件 描述 PR
--vtgate-grpc-fail-fast vtgate 启用 gRPC 快速失败模式,以便在后端不可用时获得更快的错误响应。默认:false。 #18551

修改的指标

VTOrc 恢复指标增加 Keyspace/Shard 标签

以下 VTOrc 恢复指标现在除了现有的 RecoveryType 标签外,还包含 KeyspaceShard 标签(PR #18304):

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

影响:使用这些指标的监控查询和仪表板可能需要更新以考虑额外的标签维度。

优点

  • 更细粒度地观察哪些 keyspace/shard 正在经历恢复问题
  • 能够按 keyspace/shard 设置恢复模式的警报
  • 更好地排查特定集群的问题

示例 PromQL 查询

# 之前 (v22):仅按类型统计恢复次数
sum(rate(RecoveriesCount[5m])) by (RecoveryType)

# 之后 (v23):按类型、keyspace 和 shard 统计恢复次数
sum(rate(RecoveriesCount[5m])) by (RecoveryType, Keyspace, Shard)

VTGate QueryExecutionsByTable 行为变更

QueryExecutionsByTable 指标现在仅统计成功的查询执行(PR #18584)。之前,它统计所有查询尝试,无论成功/失败。

影响

  • 如果您的工作负载有大量的查询失败,指标值可能会降低
  • 更准确地表示成功的查询量
  • 失败的查询通过错误指标单独跟踪

解析器/SQL 增强

Vitess v23.0.0 包括重大的 SQL 解析器改进,以提高 MySQL 兼容性:

新 SQL 语法支持

功能 描述 PR
CREATE TABLE ... SELECT 完全支持从 SELECT 查询结果创建表 #18443
WITH RECURSIVE 用于分层查询的递归公共表表达式 #18590
SET NAMES binary 支持二进制字符集规范 #18582
ALTER VITESS_MIGRATION ... POSTPONE COMPLETE 推迟 Online DDL 迁移完成的语法 #18118
INSERT/REPLACE 中的 VALUE 关键字 除了 VALUES 外,支持 VALUE(单数) #18116

CREATE PROCEDURE 改进

增强了 CREATE PROCEDURE 语句的解析(PR #18142PR #18279):

  • 更好地处理各种格式的 DEFINER 子句
  • 区分 BEGIN...END 块和 START TRANSACTION 语句
  • 支持过程体内的 SET 语句
  • 改进对过程定义内分号的处理

运算符优先级修复

  • 修复了 MEMBER OF 运算符与 AND 的优先级(PR #18237
  • 确保在将 JSON 操作与布尔逻辑结合时的正确查询评估

查询规划改进

单分片查询中的窗口函数

窗口函数现在可以下推到单分片查询(PR #18103),从而提高分析工作负载的性能。

v23 之前:即使对于单分片查询,窗口函数也始终在 VTGate 层执行。

v23 之后:当查询针对单个分片时,窗口函数会被下推,减少数据传输并提高性能。

示例

-- 此查询现在完全在目标分片上执行
SELECT
    user_id,
    order_date,
    amount,
    SUM(amount) OVER (PARTITION BY user_id ORDER BY order_date) as running_total
FROM orders
WHERE user_id = 12345;  -- 单分片查询

UNION 查询合并改进

UNION 查询优化得到了显著增强(PR #18289PR #18393):

扩展 UNION 合并:具有 EqualIN 操作码的 UNION 查询现在可以更积极地合并,生成更简单的 SQL。

派生表消除:避免了 UNION 查询中不必要的派生表包装,产生更简洁、更高效的 SQL。

示例

-- 查询:
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;

-- v23 之前:包装在派生表中
SELECT * FROM (
    SELECT * FROM t1 WHERE id = 1
    UNION
    SELECT * FROM t1 WHERE id = 2
) AS dt;

-- v23 之后:直接 UNION(更简单、更高效)
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;

SINGLE 模式中的多分片只读事务

使用 SINGLE 事务模式时,只读事务现在可以跨越多个分片(PR #18173)。

v23 之前:SINGLE 模式将所有事务限制在单个分片,即使是只读事务。

v23 之后:在 SINGLE 模式下,只读事务可以访问多个分片,提高了灵活性而不牺牲一致性保证。

影响:使用 SINGLE 事务模式的应用程序现在可以在事务中执行多分片读查询,无需升级到 MULTI 或 TWOPC 模式。

预处理语句的延迟优化

预处理语句现在支持延迟优化(PR #18126),即使计划生成需要运行时值也能成功准备。

优点

  • 更多预处理语句在准备阶段成功
  • 更好地支持具有参数依赖性优化的查询
  • 减少因 PREPARE 语句失败而导致的应用程序错误

行为:当预处理语句在准备阶段无法完全优化时,优化将延迟到执行阶段,届时绑定变量值可用。

INSTANT DDL 的查询缓冲

INSTANT DDL 操作实现了查询缓冲(PR #17945),减少了模式更改期间的查询失败。

功能

  • 在 INSTANT DDL 执行期间自动缓冲查询
  • 强制终止阻塞的事务
  • 对应用程序透明

影响:应用程序在模式更改期间经历更少的查询错误,提高了 DDL 操作期间的可用性。


拓扑

--consul-auth-static-file 需要 1 个或多个凭据

几个组件中使用的 --consul-auth-static-file 标志现在要求可以从提供的 JSON 文件加载 1 个或多个凭据(PR #18152)。

影响:现在配置空或无效凭据文件的启动将失败,而不是在没有身份验证的情况下静默继续。


VTOrc

聚合发现指标 HTTP API 移除

VTOrc 未记录的 /api/aggregated-discovery-metrics HTTP API 端点已被移除(PR #18672)。已记录的 VTOrc API 列表可以在 此处 找到。

我们建议使用标准的 VTOrc 指标来收集相同的指标。如果您发现标准指标中缺少某个指标,请提交 issue 或 PR 来解决。

EmergencyReparentShard 恢复的动态控制

注意:禁用 EmergencyReparentShard 恢复会带来可用性风险;请极其谨慎使用!如果您经常依赖此功能,例如在自动化中,这可能是反模式的迹象。如果是这样,请提交 issue 以讨论在 VTOrc 中原生支持您的用例。

引入了新的 vtctldclient RPC SetVtorcEmergencyReparentPR #17985),允许按 keyspace 和/或按分片禁用涉及 EmergencyReparentShard 操作的 VTOrc 恢复。在此版本之前,禁用基于 EmergencyReparentShard 的恢复仅在全球/每个 VTOrc 实例中可能。VTOrc 现在将在每次恢复时从 topo 刷新此 keyspace/分片级别设置。禁用状态由先检查 keyspace,然后检查分片状态来确定。移除 keyspace 级别覆盖不会移除每个分片的覆盖。

为了提供禁用基于 EmergencyReparentShard 的 VTOrc 恢复的 keyspace/分片的可观测性,增加了 EmergencyReparentShardDisabled 指标。此指标标签可用于创建警报,以确保基于 EmergencyReparentShard 的恢复不会在不需要的时间段内被禁用。

示例

# 禁用 keyspace 的 ERS 恢复
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --enabled=false

# 禁用特定分片的 ERS 恢复
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --shard 80- --enabled=false

# 重新启用 ERS 恢复
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --enabled=true

恢复统计信息包含 keyspace/shard

以下恢复相关统计信息现在包含 keyspace 和 shard 的标签(PR #18304):

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

在此版本之前,标签中仅包含恢复"类型"。详情请参阅 修改的指标

/api/replication-analysis HTTP API 弃用

/api/replication-analysis HTTP API 端点现已弃用,并替换为 /api/detection-analysisPR #18615),后者目前返回相同的响应格式。

时间线/api/replication-analysis 端点将在未来版本中移除。用户应迁移到 /api/detection-analysis


VTTablet

API 变更

  • TabletManagerClient 接口中添加了 RestartReplication 方法(PR #18628)。这个新的 RPC 允许在单个调用中停止和重启带有半同步配置的 MySQL 复制,为分别调用 StopReplicationStartReplication 提供了一个便捷的替代方案。

  • 添加了 GetMaxValueForSequencesUpdateSequenceTables gRPC RPC(PR #18172),用于 SwitchWrites 操作期间的 VReplication 序列管理。

CLI 标志

  • --skip-user-metrics 标志如果启用,将用户名标签替换为 “UserLabelDisabled”,以防止在具有许多唯一用户的环境中出现指标爆炸(PR #18085)。

新增标志的完整列表,请参阅 新增 CLI 标志

托管 MySQL 配置默认为 caching-sha2-password

MySQL 8.0.26 及更高版本的默认身份验证插件现在是 caching_sha2_password,而不是 mysql_native_passwordPR #18010)。此更改是因为 mysql_native_password 已弃用,并将在未来的 MySQL 版本中移除。为了向后兼容,mysql_native_password 仍然启用。

此更改特别影响复制用户。如果您有一个配置了显式密码的用户,建议在升级到 v23 后使用如下语句升级该用户:

ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password';

在未来的 Vitess 版本中,mysql_native_password 身份验证插件将被禁用于托管 MySQL 实例。

MySQL 时区环境变量传播

修复了一个错误,即像 TZ 这样的环境变量没有从 mysqlctl 传播到 mysqld 进程(PR #18561)。 因此,之前忽略了来自环境的时区设置。现在 mysqld 正确继承环境变量。

⚠️ 部署影响:依赖旧行为并显式设置非 UTC 时区的部署可能会看到 DATETIME 值解释方式的变化。为保持兼容性,请在 MySQL Pod 中显式设置 TZ=UTC

gRPC tabletmanager 客户端错误变更

vttablet gRPC tabletmanager 客户端现在返回由内部 go/vt/vterrors 包包装的错误(PR #18565)。依赖 google-gRPC 错误代码的外部自动化现在应使用 vterrors.Code(err) 来检查错误代码,该方法返回在 proto/vtrpc.proto 中定义的 vtrpcpb.Code

迁移指南请参阅 破坏性变更


Docker

Debian Bullseye 已于一年前结束支持,因此从 v23 开始,我们将不再构建或发布基于 debian:bullseye 的镜像(PR #18609)。

构建将继续支持 Debian Bookworm,并添加最近发布的 Debian Trixie。v23 明确不将默认 Debian 标签更改为 Trixie。


附加信息

此版本的完整变更日志可以在 此处 找到。

此版本包含 246 个已合并的 Pull Request。

感谢所有贡献者:@Arshdeep54、@BenjaminLockhart、@GrahamCampbell、@GuptaManan100、@HenryCaiHaiying、@app/dependabot、@app/vitess-bot、@arthurschreiber、@bantyK、@beingnoble03、@canoriz、@chapsuk、@chrisplim、@corbantek、@davidpiegza、@dbussink、@deepthi、@demmer、@derekperkins、@frouioui、@harshit-gangal、@jdoupe、@jeefy、@leejones、@mattlord、@maxenglander、@mdlayher、@mhamza15、@morgo、@mounicasruthi、@nickvanw、@notfelineit、@rohit-nayak-ps、@rvrangel、@shlomi-noach、@siddharth16396、@stankevich、@stutibiyani、@systay、@timvaillancourt、@twthorn、@vitess-bot、@wukuai、@yoheimuta

更新内容 (原始)

Release of Vitess v23.0.0

Summary

Table of Contents

Major Changes

Breaking Changes

Deleted VTGate Metrics

Four deprecated VTGate metrics have been completely removed in v23.0.0. These metrics were deprecated in v22.0.0:

Metric Name Component Deprecated In
QueriesProcessed vtgate v22.0.0
QueriesRouted vtgate v22.0.0
QueriesProcessedByTable vtgate v22.0.0
QueriesRoutedByTable vtgate v22.0.0

Impact: Any monitoring dashboards or alerting systems using these metrics must be updated to use the replacement metrics introduced in v22.0.0:

  • Use QueryExecutions instead of QueriesProcessed
  • Use QueryRoutes instead of QueriesRouted
  • Use QueryExecutionsByTable instead of QueriesProcessedByTable and QueriesRoutedByTable

See the v22.0.0 release notes for details on the new metrics.

ExecuteFetchAsDba No Longer Accepts Multi-Statement SQL

The ExecuteFetchAsDba RPC method in TabletManager now explicitly rejects SQL queries containing multiple statements (as of PR #18183).

Impact: Code or automation that previously passed multiple semicolon-separated SQL statements to ExecuteFetchAsDba will now receive an error. Each SQL statement must be sent in a separate RPC call.

Migration: Split multi-statement SQL into individual RPC calls:

// Before (no longer works):
ExecuteFetchAsDba("CREATE TABLE t1 (id INT); CREATE TABLE t2 (id INT);")

// After (required in v23+):
ExecuteFetchAsDba("CREATE TABLE t1 (id INT);")
ExecuteFetchAsDba("CREATE TABLE t2 (id INT);")

gRPC TabletManager Error Code Changes

The vttablet gRPC tabletmanager client now returns errors wrapped by the internal go/vt/vterrors package (PR #18565).

Impact: External automation relying on google-gRPC error codes must be updated to use vterrors.Code(err) to inspect error codes, which returns vtrpcpb.Codes defined in proto/vtrpc.proto.

Migration:

// Before:
if status.Code(err) == codes.NotFound { ... }

// After:
if vterrors.Code(err) == vtrpcpb.Code_NOT_FOUND { ... }

GTID API Signature Changes

Several GTID-related API signatures changed in PR #18196 as part of GTID performance optimizations:

Changed: BinlogEvent.GTID() method signature Impact: Code directly using the GTID parsing APIs may need updates. Most users are unaffected as these are internal APIs.

GenerateShardRanges API Signature Change

The key.GenerateShardRanges() function signature changed in PR #18633 to add a new hexChars int parameter controlling the hex width of generated shard names.

Impact: Code calling GenerateShardRanges() directly must be updated to pass the new parameter.

The corresponding vtctldclient command gained a new --chars flag to control this behavior.


Flag Naming Convention Migration

Vitess v23.0.0 includes a major standardization of CLI flag naming conventions across all binaries. 989 flags have been migrated from underscore notation (flag_name) to dash notation (flag-name) in PR #18280 and related PRs.

Backward Compatibility

  • v23.0.0 and v24.0.0: Both underscore and dash formats are supported. Underscore format is deprecated but functional.
  • v25.0.0: Underscore format will be removed. Only dash format will be accepted.

Automatic Normalization

Flag normalization happens automatically at the pflag level (PR #18642), so both formats are accepted without requiring code changes in v23/v24.

Example Flag Renames

Common flags affected (full list of 989 flags available in PR #18280):

Backup flags:

  • --azblob_backup_account_name--azblob-backup-account-name
  • --s3_backup_storage_bucket--s3-backup-storage-bucket
  • --xtrabackup_root_path--xtrabackup-root-path

Replication flags:

  • --heartbeat_enable--heartbeat-enable
  • --replication_connect_retry--replication-connect-retry

gRPC flags (PR #18009):

  • All gRPC-related flags standardized (30+ flags)

Action Required

Users should update configuration files, scripts, and automation to use dash-based flag names before upgrading to v25.0.0. The migration is backward compatible in v23 and v24, allowing gradual updates.


New default versions

Upgrade to MySQL 8.4

The default major MySQL version used by our vitess/lite:latest image is going from 8.0.40 to 8.4.6. This change was merged in #18569.

VTGate also advertises MySQL version 8.4.6 by default instead of 8.0.40. If that is not what you are running, you can set the mysql_server_version flag to advertise the desired version.

⚠️ Upgrading to this release with vitess-operator:

If you are using the vitess-operator, considering that we are bumping the MySQL version from 8.0.40 to 8.4.6, you will have to manually upgrade:

  1. Add innodb_fast_shutdown=0 to your extra cnf in your YAML file.
  2. Apply this file.
  3. Wait for all the pods to be healthy.
  4. Then change your YAML file to use the new Docker Images (vitess/lite:v23.0.0).
  5. Remove innodb_fast_shutdown=0 from your extra cnf in your YAML file.
  6. Apply this file.

This is only needed once when going from the latest 8.0.x to 8.4.x. Once you’re on 8.4.x, it is possible to upgrade and downgrade between 8.4.x versions without needing to run innodb_fast_shutdown=0.


New Support

Multi-Query Execution

Vitess v23.0.0 introduces native support for executing multiple queries in a single RPC call through new ExecuteMulti and StreamExecuteMulti APIs (PR #18059).

This feature provides more efficient batch query execution without requiring manual query splitting or multiple round trips.

Usage Example:

queries := []string{
    "SELECT * FROM users WHERE id = 1",
    "SELECT * FROM orders WHERE user_id = 1",
    "SELECT * FROM payments WHERE user_id = 1",
}
results, err := vtgateConn.ExecuteMulti(ctx, queries)

Configuration: Enable with the --mysql-server-multi-query-protocol flag on VTGate.

Transaction Timeout Session Variable

A new transaction_timeout session variable has been added (PR #18560), allowing per-session control over transaction timeout duration.

Usage:

-- Set transaction timeout to 30 seconds for this session
SET transaction_timeout = 30;

-- Begin a transaction that will automatically rollback if not committed within 30s
BEGIN;
-- ... perform operations ...
COMMIT;

This provides more granular timeout control compared to global server settings, useful for:

  • Long-running batch operations that need extended timeouts
  • Interactive sessions that should fail fast
  • Different timeout requirements per application workload

Experimental: Query Throttler

Vitess v23.0.0 introduces a new, experimental Query Throttler framework for rate-limiting incoming queries (RFC issue #18412, PR #18449, PR #18657). Work on this new throttler is ongoing with the potential for breaking changes in the future.

Feedback on this experimental feature is appreciated in GitHub issues or the #feat-handling-overload channel of the Vitess Community Slack.

Features:

  • File-based configuration for throttling rules
  • Dry-run mode for testing throttling without enforcement
  • Dynamic rule reloading

Configuration:

  • --query-throttler-config-refresh-interval - How often to reload throttler configuration

Dry-run Mode: Test throttling rules without actually blocking queries, useful for validating configuration before enforcement.

Multiple Lookup Vindexes Support

Creating multiple lookup vindexes in a single workflow is now supported through the --params-file flag (PR #17566).

Usage:

# Create multiple lookup vindexes from JSON configuration
vtctldclient LookupVindexCreate \
  --workflow my_lookup_workflow \
  --params-file /path/to/params.json \
  commerce

params.json example:

{
  "vindexes": [
    {
      "name": "user_email_lookup",
      "type": "consistent_lookup_unique",
      "table_owner": "users",
      "table_owner_columns": ["email"]
    },
    {
      "name": "user_name_lookup",
      "type": "consistent_lookup",
      "table_owner": "users",
      "table_owner_columns": ["name"]
    }
  ]
}

This significantly improves workflow efficiency when setting up multiple vindexes, reducing the number of separate operations required.

Reference Tables in Materialize Workflows

Reference tables can now be added to existing materialize workflows using the new Materialize ... update sub-command (PR #17804).

Usage:

# Add reference tables to an existing workflow
vtctldclient Materialize --workflow my_workflow update \
  --add-reference-tables ref_table1,ref_table2 \
  --target-keyspace my_keyspace

Use Case: Incrementally add reference tables to running materialize workflows without recreating the entire workflow, improving operational flexibility.

Online DDL Shard-Specific Completion

Online DDL migrations can now be completed on a per-shard basis using the new COMPLETE VITESS_SHARDS syntax (PR #18331).

Usage:

-- Complete migration on specific shards only
ALTER VITESS_MIGRATION '9e8a9249_3976_11ed_9442_0a43f95f28a3'
  COMPLETE VITESS_SHARDS '-80,80-';

-- Complete migration on all remaining shards
ALTER VITESS_MIGRATION '9e8a9249_3976_11ed_9442_0a43f95f28a3'
  COMPLETE;

Benefits:

  • Gradual rollout of schema changes across shards
  • Ability to validate changes on subset of shards before full rollout
  • Better control over migration timing and impact

WITH RECURSIVE CTEs

Vitess now supports WITH RECURSIVE common table expressions (PR #18590), enabling recursive queries for hierarchical data.

Example:

-- Find all employees in a management hierarchy
WITH RECURSIVE employee_hierarchy AS (
    SELECT id, name, manager_id, 1 as level
    FROM employees
    WHERE manager_id IS NULL

    UNION ALL

    SELECT e.id, e.name, e.manager_id, eh.level + 1
    FROM employees e
    INNER JOIN employee_hierarchy eh ON e.manager_id = eh.id
)
SELECT * FROM employee_hierarchy ORDER BY level, name;

This is a major SQL compatibility enhancement for applications with hierarchical or graph-like data structures.

CREATE TABLE … SELECT Support

The SQL parser now supports CREATE TABLE ... SELECT statements (PR #18443), improving MySQL compatibility.

Example:

-- Create a table from a query result
CREATE TABLE recent_orders
SELECT * FROM orders
WHERE order_date > DATE_SUB(NOW(), INTERVAL 30 DAY);

Deprecations

Metrics

Component Metric Name Notes Deprecation PR
vtorc DiscoverInstanceTimings Replaced by DiscoveryInstanceTimings #18406

CLI Flags

As part of the Flag Naming Convention Migration, 989 CLI flags across all Vitess binaries have been deprecated in their underscore format. The dash format should be used going forward.

Deprecation Timeline:

  • v23.0.0 and v24.0.0: Underscore format deprecated but functional
  • v25.0.0: Underscore format will be removed

Action Required: Migrate to dash-based flag names before v25.0.0. See Flag Naming Convention Migration for details.


Deletions

Metrics

Component Metric Name Was Deprecated In Deprecation PR
vtgate QueriesProcessed v22.0.0 #17727
vtgate QueriesRouted v22.0.0 #17727
vtgate QueriesProcessedByTable v22.0.0 #17727
vtgate QueriesRoutedByTable v22.0.0 #17727

See Breaking Changes for migration guidance.


New Metrics

VTGate

Name Dimensions Description PR
TransactionsProcessed Shard, Type Counts transactions processed at VTGate by shard distribution and transaction type. #18171
OptimizedQueryExecutions N/A Counter tracking queries that used deferred optimization execution path. #18067

Transaction Types in TransactionsProcessed:

  • Single - Single-shard transactions
  • Multi - Multi-shard transactions
  • TwoPC - Two-phase commit transactions

Use Case: The TransactionsProcessed metric helps identify transaction patterns and shard distribution, useful for:

  • Monitoring transaction types across your deployment
  • Identifying queries that could be optimized to single-shard
  • Tracking two-phase commit usage and potential bottlenecks

VTTablet

Name Dimensions Description PR
OnlineDDLStaleMigrationMinutes N/A Minutes since the oldest pending/ready migration was submitted. #18417
vttablet_tablet_server_state type, keyspace, shard Enhanced with additional dimensions for better observability. #18451

Use Case for OnlineDDLStaleMigrationMinutes: Alert on stalled Online DDL migrations that haven’t progressed for an extended period, helping identify migrations that may need intervention.

VTOrc

Name Dimensions Description PR
SkippedRecoveries RecoveryName, Keyspace, Shard, Reason Count of skipped recoveries with reason tracking. #18644
EmergencyReparentShardDisabled Keyspace, Shard Gauge indicating if ERS is disabled per keyspace/shard. #17985

Use Case for EmergencyReparentShardDisabled: Create alerts to ensure EmergencyReparentShard-based recoveries are not disabled for an undesired period, maintaining high availability posture.

SkippedRecoveries Reasons: The Reason dimension tracks why recoveries were skipped (e.g., “ERSDisabled”, “ReplicationLagHigh”, “NotEnoughReplicas”), providing actionable insights for operational troubleshooting.


Minor Changes

New CLI Flags

VReplication/Materialize

Flag Component Description PR
--params-file vtctldclient JSON file containing lookup vindex parameters for creating multiple lookup vindexes in a single workflow. Mutually exclusive with --type, --table-owner, and --table-owner-columns. #17566
--add-reference-tables vtctldclient Comma-separated list of reference tables to add to an existing materialize workflow using the update sub-command. #17804

Observability

Flag Component Description PR
--skip-user-metrics vttablet If enabled, replaces the username label in user-based metrics with “UserLabelDisabled” to prevent metric cardinality explosion in environments with many unique users. #18085
--querylog-emit-on-any-condition-met vtgate, vttablet, vtcombo Changes query log emission to emit when ANY logging condition is met (row-threshold, time-threshold, filter-tag, or error) rather than requiring ALL conditions. Default: false. #18546
--querylog-time-threshold vtgate, vttablet Duration threshold for query logging. Queries exceeding this duration will be logged. Works with --querylog-emit-on-any-condition-met. #18520
--grpc-enable-orca-metrics vtgate, vttablet Enable ORCA (Open Request Cost Aggregation) backend metrics reporting via gRPC for load balancing decisions. Default: false. #18282
--datadog-trace-debug-mode All components Makes Datadog trace debug mode configurable instead of always-on. Default: false. #18347

VTOrc

Flag Component Description PR
--allow-recovery vtorc Boolean flag to disable all VTOrc recovery operations from startup. When false, VTOrc runs in monitoring-only mode. Default: true. #18005

Use Case: The --allow-recovery=false flag is useful for:

  • Testing VTOrc capacity/discovery performance ahead of a rollout, for example: migrating to VTOrc from another solution.
  • Maintenance windows where automatic failovers should be prevented
  • Debugging VTOrc behavior without triggering recoveries
  • Running VTOrc in observation-only mode

Backup/Restore

Flag Component Description PR
--xtrabackup-should-drain vttablet Makes the ShouldDrainForBackup behavior configurable for xtrabackup engine. When true, tablet drains traffic before backup. Default: true. #18431

CLI Tools

Flag Component Description PR
--chars vtctldclient Specifies the hex width (number of hex characters) to use when generating shard ranges with GenerateShardRanges command. Allows fine-grained control over shard naming. #18633

Example:

# Generate shard ranges with 4 hex characters
vtctldclient GenerateShardRanges --shards 16 --chars 4
# Output: -1000,1000-2000,2000-3000,...,f000-

VTAdmin

Five new TLS-related flags were added for secure vtctld connections (PR #18556):

Flag Description
--vtctld-grpc-ca CA certificate file for vtctld gRPC TLS
--vtctld-grpc-cert Client certificate file for vtctld gRPC TLS
--vtctld-grpc-key Client key file for vtctld gRPC TLS
--vtctld-grpc-server-name Server name for vtctld gRPC TLS validation
--vtctld-grpc-crl Certificate revocation list for vtctld gRPC TLS

These flags enable mTLS (mutual TLS) authentication between VTAdmin and vtctld for enhanced security.

VTGate

Flag Component Description PR
--vtgate-grpc-fail-fast vtgate Enable gRPC fail-fast mode for faster error responses when backends are unavailable. Default: false. #18551

Modified Metrics

VTOrc Recovery Metrics Enhanced with Keyspace/Shard Labels

The following VTOrc recovery metrics now include Keyspace and Shard labels in addition to the existing RecoveryType label (PR #18304):

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

Impact: Monitoring queries and dashboards using these metrics may need updates to account for the additional label dimensions.

Benefits:

  • More granular observability into which keyspaces/shards are experiencing recovery issues
  • Ability to alert on recovery patterns per keyspace/shard
  • Better troubleshooting of cluster-specific issues

Example PromQL Query:

# Before (v22): Recovery count by type only
sum(rate(RecoveriesCount[5m])) by (RecoveryType)

# After (v23): Recovery count by type, keyspace, and shard
sum(rate(RecoveriesCount[5m])) by (RecoveryType, Keyspace, Shard)

VTGate QueryExecutionsByTable Behavior Change

The QueryExecutionsByTable metric now only counts successful query executions (PR #18584). Previously, it counted all query attempts regardless of success/failure.

Impact:

  • Metric values may decrease if your workload had significant query failures
  • More accurate representation of successful query volume
  • Failed queries are tracked separately via error metrics

Parser/SQL Enhancements

Vitess v23.0.0 includes significant SQL parser improvements for better MySQL compatibility:

New SQL Syntax Support

Feature Description PR
CREATE TABLE ... SELECT Full support for creating tables from SELECT query results #18443
WITH RECURSIVE Recursive common table expressions for hierarchical queries #18590
SET NAMES binary Support for binary character set specification #18582
ALTER VITESS_MIGRATION ... POSTPONE COMPLETE Syntax for postponing Online DDL migration completion #18118
VALUE keyword in INSERT/REPLACE Support for VALUE (singular) in addition to VALUES #18116

CREATE PROCEDURE Improvements

Enhanced CREATE PROCEDURE statement parsing (PR #18142, PR #18279):

  • Better handling of DEFINER clauses with various formats
  • Differentiation between BEGIN...END blocks and START TRANSACTION statements
  • Support for SET statements within procedure bodies
  • Improved handling of semicolons within procedure definitions

Operator Precedence Fixes

  • Fixed MEMBER OF operator precedence with AND (PR #18237)
  • Ensures correct query evaluation when combining JSON operations with boolean logic

Query Planning Improvements

Window Functions in Single-Shard Queries

Window functions can now be pushed down to single-shard queries (PR #18103), improving performance for analytics workloads.

Before v23: Window functions were always executed at VTGate level, even for single-shard queries.

After v23: Window functions are pushed down when the query targets a single shard, reducing data transfer and improving performance.

Example:

-- This query now executes entirely on the target shard
SELECT
    user_id,
    order_date,
    amount,
    SUM(amount) OVER (PARTITION BY user_id ORDER BY order_date) as running_total
FROM orders
WHERE user_id = 12345;  -- Single-shard query

UNION Query Merging Improvements

UNION query optimization has been significantly enhanced (PR #18289, PR #18393):

Extended UNION Merging: UNION queries with Equal and IN opcodes can now be merged more aggressively, generating simpler SQL.

Derived Table Elimination: Unnecessary derived table wrapping is avoided for UNION queries, producing cleaner and more efficient SQL.

Example:

-- Query:
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;

-- Before v23: Wrapped in derived table
SELECT * FROM (
    SELECT * FROM t1 WHERE id = 1
    UNION
    SELECT * FROM t1 WHERE id = 2
) AS dt;

-- After v23: Direct UNION (simpler, more efficient)
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;

Multi-Shard Read-Only Transactions in SINGLE Mode

Read-only transactions can now span multiple shards when using SINGLE transaction mode (PR #18173).

Before v23: SINGLE mode restricted all transactions to single shards, even read-only ones.

After v23: Read-only transactions can access multiple shards in SINGLE mode, improving flexibility without sacrificing consistency guarantees.

Impact: Applications using SINGLE transaction mode can now perform multi-shard read queries within transactions without needing to upgrade to MULTI or TWOPC modes.

Deferred Optimization for Prepared Statements

Prepared statements now support deferred optimization (PR #18126), allowing preparation to succeed even when plan generation requires runtime values.

Benefits:

  • More prepared statements succeed at preparation time
  • Better support for queries with parameter-dependent optimization
  • Reduced application errors from failed PREPARE statements

Behavior: When a prepared statement cannot be fully optimized at preparation time, optimization is deferred to execution time when bind variable values are available.

Query Buffering for INSTANT DDL

Query buffering has been implemented for INSTANT DDL operations (PR #17945), reducing query failures during schema changes.

Features:

  • Automatic buffering of queries during INSTANT DDL execution
  • Forced termination of blocking transactions
  • Transparent to applications

Impact: Applications experience fewer query errors during schema changes, improving availability during DDL operations.


Topology

--consul-auth-static-file requires 1 or more credentials

The --consul-auth-static-file flag used in several components now requires that 1 or more credentials can be loaded from the provided json file (PR #18152).

Impact: Configurations with empty or invalid credential files will now fail at startup rather than silently continuing with no authentication.


VTOrc

Aggregated Discovery Metrics HTTP API removed

VTOrc’s undocumented /api/aggregated-discovery-metrics HTTP API endpoint was removed (PR #18672). The list of documented VTOrc APIs can be found here.

We recommend using the standard VTOrc metrics to gather the same metrics. If you find that a metric is missing in standard metrics, please open an issue or PR to address this.

Dynamic control of EmergencyReparentShard-based recoveries

Note: disabling EmergencyReparentShard-based recoveries introduces availability risks; please use with extreme caution! If you rely on this functionality often, for example in automation, this may be signs of an anti-pattern. If so, please open an issue to discuss supporting your use case natively in VTOrc.

The new vtctldclient RPC SetVtorcEmergencyReparent was introduced (PR #17985) to allow VTOrc recoveries involving EmergencyReparentShard actions to be disabled on a per-keyspace and/or per-shard basis. Previous to this version, disabling EmergencyReparentShard-based recoveries was only possible globally/per-VTOrc-instance. VTOrc will now consider this keyspace/shard-level setting that is refreshed from the topo on each recovery. The disabled state is determined by first checking if the keyspace, and then the shard state. Removing a keyspace-level override does not remove per-shard overrides.

To provide observability of keyspaces/shards with EmergencyReparentShard-based VTOrc recoveries disabled, the EmergencyReparentShardDisabled metric was added. This metric label can be used to create alerting to ensure EmergencyReparentShard-based recoveries are not disabled for an undesired period of time.

Example:

# Disable ERS recoveries for a keyspace
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --enabled=false

# Disable ERS recoveries for a specific shard
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --shard 80- --enabled=false

# Re-enable ERS recoveries
vtctldclient SetVtorcEmergencyReparent --keyspace commerce --enabled=true

Recovery stats to include keyspace/shard

The following recovery-related stats now include labels for keyspaces and shards (PR #18304):

  1. FailedRecoveries
  2. PendingRecoveries
  3. RecoveriesCount
  4. SuccessfulRecoveries

Previous to this release, only the recovery “type” was included in labels. See Modified Metrics for more details.

/api/replication-analysis HTTP API deprecation

The /api/replication-analysis HTTP API endpoint is now deprecated and is replaced with /api/detection-analysis (PR #18615), which currently returns the same response format.

Timeline: The /api/replication-analysis endpoint will be removed in a future version. Users should migrate to /api/detection-analysis.


VTTablet

API Changes

  • Added RestartReplication method to TabletManagerClient interface (PR #18628). This new RPC allows stopping and restarting MySQL replication with semi-sync configuration in a single call, providing a convenient alternative to separate StopReplication and StartReplication calls.

  • Added GetMaxValueForSequences and UpdateSequenceTables gRPC RPCs (PR #18172) for VReplication sequence management during SwitchWrites operations.

CLI Flags

  • --skip-user-metrics flag if enabled, replaces the username label with “UserLabelDisabled” to prevent metric explosion in environments with many unique users (PR #18085).

See New CLI Flags for complete list of new flags.

Managed MySQL configuration defaults to caching-sha2-password

The default authentication plugin for MySQL 8.0.26 and later is now caching_sha2_password instead of mysql_native_password (PR #18010). This change is made because mysql_native_password is deprecated and removed in future MySQL versions. mysql_native_password is still enabled for backwards compatibility.

This change specifically affects the replication user. If you have a user configured with an explicit password, it is recommended to make sure to upgrade this user after upgrading to v23 with a statement like the following:

ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password';

In future Vitess versions, the mysql_native_password authentication plugin will be disabled for managed MySQL instances.

MySQL timezone environment propagation

Fixed a bug where environment variables like TZ were not propagated from mysqlctl to the mysqld process (PR #18561). As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables.

⚠️ Deployment Impact: Deployments that relied on the old behavior and explicitly set a non-UTC timezone may see changes in how DATETIME values are interpreted. To preserve compatibility, set TZ=UTC explicitly in MySQL pods.

gRPC tabletmanager client error changes

The vttablet gRPC tabletmanager client now returns errors wrapped by the internal go/vt/vterrors package (PR #18565). External automation relying on google-gRPC error codes should now use vterrors.Code(err) to inspect the code of an error, which returns vtrpcpb.Codes defined in the proto/vtrpc.proto protobuf.

See Breaking Changes for migration guidance.


Docker

Bullseye went EOL 1 year ago, so starting from v23, we will no longer build or publish images based on debian:bullseye (PR #18609).

Builds will continue for Debian Bookworm, and add the recently released Debian Trixie. v23 explicitly does not change the default Debian tag to Trixie.


Additional Information

The entire changelog for this release can be found here.

The release includes 246 merged Pull Requests.

Thanks to all our contributors: @Arshdeep54, @BenjaminLockhart, @GrahamCampbell, @GuptaManan100, @HenryCaiHaiying, @app/dependabot, @app/vitess-bot, @arthurschreiber, @bantyK, @beingnoble03, @canoriz, @chapsuk, @chrisplim, @corbantek, @davidpiegza, @dbussink, @deepthi, @demmer, @derekperkins, @frouioui, @harshit-gangal, @jdoupe, @jeefy, @leejones, @mattlord, @maxenglander, @mdlayher, @mhamza15, @morgo, @mounicasruthi, @nickvanw, @notfelineit, @rohit-nayak-ps, @rvrangel, @shlomi-noach, @siddharth16396, @stankevich, @stutibiyani, @systay, @timvaillancourt, @twthorn, @vitess-bot, @wukuai, @yoheimuta

下载链接