发布日期: 2026-04-30
版本号: v24.0.0

Vitess v24.0.0 发布版本带来了多项重要更新。主要变更包括：针对分片键空间新增窗口函数下推优化；支持视图路由规则，允许将查询重写至目标视图定义；VTGate 扩展了 USE 语句语法，支持通过别名将查询路由到特定 Tablet；新增了基于 GTID 的 binlog 流式传输支持，并默认启用结构化 JSON 日志。破坏性变更方面，恢复备份时不再默认使用备份清单中存储的外部解压命令，需显式启用新标志。

次要变更涵盖多个组件：VReplication 的 MoveTables/Reshard 工作流新增 --shards 标志支持按分片启动/停止，并能自动重试遇到特定错误的 Tablet；VTGate 移除了 --grpc-send-session-in-streaming 标志，并为 --vtgate-balancer-mode 新增了“session”模式；查询服务中 JSON_EXTRACT 函数现支持动态路径参数；VTTablet 增加了实验性标志 --init-tablet-type-lookup 以自动恢复 Tablet 类型，并扩展了查询节流器的可观测性指标；追踪功能新增了对 OpenTelemetry 的支持，同时弃用了基于 OpenTracing 的后端；VTOrc 新增 --cell 标志、优化了恢复执行顺序并移除了部分已弃用功能；指标系统扩展了 Go 运行时指标的导出；备份恢复支持使用 MySQL CLONE 插件直接克隆数据以快速配置副本，并改进了恢复钩子的功能。

更新内容 （中文）

Vitess v24.0.0 发布

概述

目录

<a id="主要变更"/>主要变更

<a id="新增支持"/>新增支持

<a id="窗口函数下推"/>分片键空间的窗口函数下推

此版本引入了一项优化，允许当窗口函数按与唯一 vindex 匹配的列分区时，将其下推到各个分片执行。

此前，所有窗口函数查询都需要单分片路由，这限制了它们在分片表上的适用性。通过此更改，PARTITION BY 子句与唯一 vindex 对齐的查询现在可以被下推并在每个分片上执行。

有关示例和更多详情，请参阅文档。

<a id="视图路由规则"/>视图路由规则

Vitess 现在支持视图的路由规则，并且可以通过 vtctldclient ApplyRoutingRules 以与表相同的方式应用。当视图路由规则激活时，VTGate 会重写引用源视图的查询，以使用目标视图的定义。例如，给定此路由规则：

{
  \"rules\": [
    {
      \"from_table\": \"source_ks.my_view\",
      \"to_tables\": [\"target_ks.my_view\"]
    }
  ]
}

以及此视图定义：

CREATE VIEW target_ks.my_view AS SELECT id, name FROM user;

像 SELECT * FROM source_ks.my_view 这样的查询将在内部被重写为：

SELECT * FROM (SELECT id, name FROM target_ks.user) AS my_view;

视图路由规则要求 Schema 跟踪器监控视图，这意味着 VTGate 必须使用 --enable-views 标志启动，VTTablet 必须使用 --queryserver-enable-views 标志启动。目标视图必须存在于指定的键空间中，路由规则才能正确运行。更多详情，请参阅 Schema 路由规则文档。

<a id="tablet定位"/>通过 USE 语句定位 Tablet

VTGate 现在支持通过扩展的 USE 语句语法按别名将查询路由到特定 Tablet：

USE keyspace:shard@tablet_type|tablet_alias;

例如，要定位一个特定的副本 Tablet：

USE commerce:-80@replica|zone1-0000000100;

设置后，会话中的所有后续查询将路由到指定的 Tablet，直到使用标准 USE keyspace 或 USE keyspace@tablet_type 语句清除。这对于调试、每个 Tablet 的监控、缓存预热以及其他需要定位特定 Tablet 的操作任务很有用。

注意：使用 Tablet 定位时必须指定分片。与分片定位一样，这会绕过基于 vindex 的路由，因此请谨慎使用。

<a id="vtgate-binlog-转储"/>Binlog 流式传输支持

VTGate 现在通过两种协议支持基于 GTID 的 binlog 流式传输：

  • MySQL 协议：客户端可以使用标准 MySQL COM_BINLOG_DUMP_GTID 复制协议命令连接——无需特殊的 VStream 感知适配器或直接 MySQL 访问。
  • gRPC：vtgateservice 中新的 BinlogDumpGTID 流式 RPC 为自定义客户端提供了原生 gRPC 访问，无需 MySQL 协议依赖。

注意：仅支持基于 GTID 的流式传输。通过 COM_BINLOG_DUMP 或 COM_BINLOG_DUMP_GTID 均不可用基于文件/位置的流式传输，会返回错误。

此功能默认禁用。使用 --enable-binlog-dump 启用它。

新标志：

  • --enable-binlog-dump：启用 binlog dump 支持。没有此标志，binlog dump 请求会返回错误。
  • --binlog-dump-authorized-users：授权执行 binlog dump 操作的用户逗号分隔列表，或 % 允许所有用户。

要求：

发起 binlog dump 连接时，客户端必须指定：

  • 空文件名
  • 文件位置 (filepos) 为 4
  • GTID 位置

对于 gRPC 客户端，直接在 BinlogDumpGTIDRequest 中指定键空间、分片，以及可选的 Tablet 类型或 Tablet 别名。

限制：

  • 每个流在单个 Tablet 上运行——没有跨分片的数据聚合。
  • 没有自动故障转移——如果目标 Tablet 变得不可用，流将失败，客户端必须重新连接到另一个 Tablet。
  • 与 MoveTables 或 Reshard 操作不兼容。这些用例请使用 VStream API。

<a id="结构化日志"/>结构化日志

Vitess 现在默认使用结构化 JSON 日志。日志输出以 JSON 格式输出到 stderr。要配置最低日志级别，请传递 --log-level（debug、info、warn、error 之一；默认 info）。要获得带自动颜色检测的人类可读格式，请传递 --log-format=text。要恢复到之前的 glog 后端，请传递 --log-structured=false。

从 v24 起，glog 已弃用，将在 v25 中移除。

<a id="破坏性变更"/>破坏性变更

<a id="vttablet-外部解压器-manifest"/>默认不再从备份 MANIFEST 中读取外部解压器

存储在备份 MANIFEST 文件中的外部解压器命令在恢复时默认不再使用。此前，当未提供 --external-decompressor 标志时，VTTablet 会回退到 MANIFEST 中指定的命令。这存在安全风险：对备份存储有写访问权限的攻击者可以修改 MANIFEST，从而在 Tablet 上执行任意命令。

从 v24 开始，除非您通过新的 --external-decompressor-use-manifest 标志明确选择加入，否则将忽略基于 MANIFEST 的解压器。如果您依赖此行为，请将该标志添加到您的 VTTablet 配置中，但请注意其安全影响。

详情请参阅 #19460。

<a id="次要变更"/>次要变更

<a id="次要变更-vreplication"/>VReplication

<a id="vreplication-shards-标志-启动停止"/>--shards 标志用于 MoveTables/Reshard 启动和停止

MoveTables 和 Reshard 工作流的 start 和 stop 命令现在支持 --shards 标志，允许用户在特定分片子集上启动或停止工作流，而不是一次在所有分片上操作。

示例用法：

# 仅在特定分片上启动工作流
vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer start --shards=\"-80,80-\"

# 仅在特定分片上停止工作流
vtctldclient Reshard --target-keyspace customer --workflow cust2cust stop --shards=\"80-\"

<a id="vreplication-tablet错误重试"/>针对 Tablet 特定错误的自动 Tablet 重试

VReplication 工作流现在在遇到 Tablet 特定错误时自动使用不同的 Tablet 进行重试。此前，没有 Cell 偏好的工作流会默认使用本地 Cell，并可能无限期地重试同一个失败的 Tablet。

当 Tablet 遇到诸如二进制日志清除（MySQL 错误 1236 或 1789）或 GTID 集不匹配等错误时，VReplication 会将该 Tablet 添加到忽略列表中，并尝试所有 Cell 中的其他 Tablet。一旦所有匹配的 Tablet 都已尝试，忽略列表将被清除，工作流将从头开始重试。

这在多 Cell 部署中特别有用，其中本地 Cell 中的 Tablet 可能缺少所需的二进制日志，但其他 Cell 中的 Tablet 仍然拥有它们。

<a id="次要变更-vtgate"/>VTGate

<a id="vtgate-移除-grpc-send-session-in-streaming"/>移除 --grpc-send-session-in-streaming 标志

VTGate 标志 --grpc-send-session-in-streaming 已被移除。此标志在 v22 中通过 #17907 弃用，并默认为 true。

现在，会话始终作为流式响应中的最后一个数据包发送，用于 StreamExecute 和 StreamExecuteMulti RPC。此行为是支持流式传输中事务所必需的，无法禁用。

影响：从 VTGate 启动脚本或配置中移除任何对 --grpc-send-session-in-streaming 标志的使用。

<a id="vtgate-新默认值-legacy-replication-lag-algorithm"/>--legacy-replication-lag-algorithm 标志的新默认值

VTGate 标志 --legacy-replication-lag-algorithm 现在默认为 false，默认禁用处理复制延迟的旧方法。

取而代之的是使用一种更简单的算法，纯粹基于低延迟、高延迟和最小 Tablet 数量，这在许多生产环境中已被证明更稳定。这两种方法的详细解释在此代码注释中。

在 v25 中，此标志将被弃用，并在下一个版本中移除。同时，可以通过设置 --legacy-replication-lag-algorithm=true 来使用旧行为。此弃用跟踪在 https://github.com/vitessio/vitess/issues/18914。

<a id="vtgate-session-平衡器模式"/>--vtgate-balancer-mode 标志的新增 "session" 模式

VTGate 标志 --vtgate-balancer-mode 除了现有的 "cell"、"prefer-cell" 和 "random" 模式外，现在支持新的 "session" 模式。会话模式在会话持续期间将每个会话始终一致地路由到同一个 Tablet。

要启用会话模式，请在启动 VTGate 时设置该标志：

--vtgate-balancer-mode=session

<a id="次要变更-查询服务"/>查询服务

<a id="查询服务-json-extract-动态参数"/>JSON_EXTRACT 现在支持动态路径参数

JSON_EXTRACT 函数现在支持动态路径参数，例如绑定变量或其他函数调用的结果。此前，JSON_EXTRACT 仅对路径参数使用静态字符串字面量。

NULL 处理现在与 MySQL 行为匹配。当文档或路径参数为 NULL 时，函数返回 NULL。

即使与动态参数混合使用，静态路径参数仍然会被优化，因此现有查询不会看到任何性能下降。

<a id="次要变更-vttablet"/>VTTablet

<a id="vttablet-初始-tablet-类型查找"/>新增实验性标志 --init-tablet-type-lookup

VTTablet 的新实验性标志 --init-tablet-type-lookup 允许 Tablet 在重启时通过查找现有的拓扑记录自动恢复其之前的 Tablet 类型，而不是始终使用静态的 --init-tablet-type 值。

启用后，Tablet 在重启时使用其别名从现有的拓扑记录中查找 Tablet 类型。这允许 Tablet 在重启期间保持其更改的角色（例如 RDONLY/DRAINED），而无需手动重新配置。如果禁用或不存在拓扑记录，则将使用标准的 --init-tablet-type 值。

注意：Vitess Operator 管理的部署通常不会在 Pod 替换过程中保持 topo 中匹配的 Tablet 记录，因此此功能在这些环境中效果有限。

<a id="vttablet-querythrottler-指标"/>QueryThrottler 可观测性指标

VTTablet 现在暴露了用于跟踪 QueryThrottler 行为的新指标。

新增了四个指标：

  • QueryThrottlerRequests：查询节流器评估的请求总数
  • QueryThrottlerThrottled：被节流的请求数
  • QueryThrottlerTotalLatencyNs：每个请求在查询节流中花费的总时间，包括评估、指标检查和其他开销（以纳秒为单位）
  • QueryThrottlerEvaluateLatencyNs：做出节流决策所花费的时间（以纳秒为单位）

所有指标都包含 Strategy、Workload 和 Priority 的标签。QueryThrottlerThrottled 指标具有额外的 MetricName、MetricValue 和 DryRun 标签，以识别是哪个指标触发了节流以及是否在试运行模式下发生。

这些指标有助于监控节流模式、识别哪些工作负载被节流、衡量性能开销，并在配置更改之前验证试运行模式下的行为。

<a id="vttablet-querythrottler-配置监听"/>QueryThrottler 事件驱动配置更新

QueryThrottler 配置现在被传播到拓扑服务器中的 SrvKeyspace 记录，并使用标准拓扑工具进行管理。此前，Tablet 每 60 秒轮询一次配置更改。Tablet 现在使用事件驱动监视（WatchSrvKeyspace）在查询节流配置更改时立即接收更新。键空间中的所有 Tablet 大约同时看到配置更改，并且拓扑服务器的更改是版本化和可审计的。

此更改用存储在拓扑中的基于 protobuf 定义的配置结构取代了先前的基于文件的配置加载器。新配置包括用于启用/禁用节流、选择节流策略和配置特定于策略的规则的字段。

<a id="vttablet-连接池-等待者上限"/>Tablet 连接池等待者上限

VTTablet 现在允许用户对从连接池等待获取连接的请求数量设置限制，适用于查询、流式和事务连接池。限制通过以下标志设置：

  • --queryserver-config-query-pool-waiter-cap
  • --queryserver-config-stream-pool-waiter-cap
  • --queryserver-config-txpool-waiter-cap

以上所有标志的默认值均为 0，表示无限制，从而保留了先前版本的行为。

<a id="次要变更-链路追踪"/>链路追踪

<a id="链路追踪-opentelemetry"/>OpenTelemetry 链路追踪支持

Vitess 现在支持 OpenTelemetry 作为链路追踪后端。要使用它，在任何 Vitess 二进制文件上设置 --tracer opentelemetry。跟踪通过 OTLP/gRPC 导出，可通过以下标志进行配置：

  • --otel-endpoint：OpenTelemetry 收集器端点。如果为空，则使用 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量；如果该变量也未设置，OpenTelemetry SDK 默认使用 localhost:4317。
  • --otel-insecure（默认 false）：使用非安全连接到收集器。
  • --tracing-sampling-rate（默认 0.1）：跟踪的采样率（所有链路追踪后端共享）。

任何兼容 OTLP 的后端（Jaeger v1.35+、Grafana Tempo、Datadog Agent 等）都可以接收这些跟踪。

<a id="链路追踪-opentracing-弃用"/>弃用基于 OpenTracing 的链路追踪后端

以下链路追踪后端从 v24 起已弃用，将在 v25 中移除：

  • opentracing-jaeger — 使用 Jaeger client-go 库，该库已归档。Jaeger 项目建议迁移到 OpenTelemetry。用户应迁移到 --tracer opentelemetry 并使用兼容 OTLP 的 Jaeger 端点（v1.35+）。
  • opentracing-datadog — 使用 dd-trace-go 中的 OpenTracing 桥接。用户应迁移到 --tracer opentelemetry 并使用 Datadog Agent 的 OTLP 摄取端点。

--tracer opentracing-jaeger 和 --tracer opentracing-datadog 选项在 v24 中继续有效，但在启动时会记录弃用警告。以下特定于 Jaeger 的标志也已弃用，将在 v25 中移除：

  • --jaeger-agent-host
  • --tracing-sampling-type

迁移：将 --tracer opentracing-jaeger 替换为 --tracer opentelemetry，将 --jaeger-agent-host host:port 替换为 --otel-endpoint host:4317。确保您的 Jaeger 部署接受 OTLP（Jaeger v1.35+ 默认监听端口 4317）。

<a id="次要变更-vtorc"/>VTOrc

<a id="vtorc-cell-标志"/>新增 --cell 标志

VTOrc 现在支持 --cell 标志，用于指定 VTOrc 进程运行所在的 Vitess Cell。此标志在 v24 中是可选的，但在 v25+ 中将是必需的，类似于 VTGate 的 --cell 标志。

提供该标志时，VTOrc 会在启动时验证该 Cell 是否存在于拓扑服务中。如果不提供该标志，VTOrc 会记录一条关于 v25+ 标志要求的警告。

这使得未来的跨 Cell 问题验证成为可能，届时 VTOrc 将能够要求另一个 Cell 在采取恢复操作之前验证检测到的问题。该标志目前在 VTOrc 恢复逻辑中已进行验证但尚未使用。

注意：如果您在多 Cell 部署中运行 VTOrc，请现在开始使用 --cell 标志，为 v25 的要求做准备。

<a id="vtorc-有序恢复-半同步"/>有序恢复执行与半同步部署

VTOrc 现在按分片执行具有定义顺序的恢复，而不是单独按 Tablet 执行。具有顺序依赖关系（例如半同步配置）的问题将首先串行执行，而独立问题则并发执行。这确保了在分片内依赖关系的恢复按正确顺序发生。

主要面向用户的改进是针对半同步部署：VTOrc 现在确保在更新主库之前，副本已启用半同步。此前，在主库上启用半同步之前，如果副本尚未准备好，可能会导致写操作停滞，因为主库在等待没有副本准备发送的半同步确认。

详情请参阅 #19427。

<a id="vtorc-已弃用指标已移除"/>已弃用 VTOrc 指标已移除

VTOrc 中的 DiscoverInstanceTimings 指标已在 v24 中移除。此指标在 v23 中已弃用。

迁移：请改用 DiscoveryInstanceTimings，它提供相同的实例发现操作（Backend、Instance、Other）的计时信息。

影响：使用 DiscoverInstanceTimings 的监控仪表板或告警系统必须更新为使用 DiscoveryInstanceTimings。

<a id="vtorc-快照拓扑弃用"/>弃用快照拓扑功能

VTOrc 的快照拓扑功能（通过将 --snapshot-topology-interval 设置为非零值启用）从 v24 起已弃用，其逻辑计划在 v25 中移除。

缺乏读取此功能创建的快照的设施，加上 VTOrc 后端的内存性质，意味着此逻辑的用途有限。此弃用在 https://github.com/vitessio/vitess/issues/18691 中有详细说明和跟踪。

迁移：在 v25 之前移除 VTOrc 标志 --snapshot-topology-interval。

影响：VTOrc 将无法再在其后端数据库中创建拓扑快照。

<a id="vtorc-replication-analysis-api-已移除"/>已弃用 /api/replication-analysis 端点已移除

/api/replication-analysis 端点已在 v24 中从 VTOrc 中移除。请改用 /api/detection-analysis，它提供相同的功能。

迁移：更新任何调用 /api/replication-analysis 的脚本、监控系统或自动化工具，改用 /api/detection-analysis。替代端点接受相同的查询参数（keyspace、shard）并返回相同的 JSON 响应格式。

影响：对 /api/replication-analysis 的 HTTP 请求将返回 404 Not Found 错误。

<a id="次要变更-指标"/>指标

<a id="指标-扩展-go-运行时"/>通过 Prometheus 扩展 Go 运行时指标

Vitess 现在通过 Prometheus 暴露完整的 Go 运行时指标集。默认的 Prometheus GoCollector 仅暴露三个 runtime/metrics（/gc/gogc:percent、/gc/gomemlimit:bytes、/sched/gomaxprocs:threads）以及旧版 go_memstats_* 系列。从 v24 开始，所有 Vitess 组件暴露大约 150 个来自 Go runtime/metrics 包的额外指标。

新指标包括：

  • 堆分配直方图
  • GC 周期计数和暂停直方图
  • 内存分类细分
  • Goroutine 状态细分
  • 调度器延迟直方图
  • 按类别（用户、GC、清理、空闲）的 CPU 时间细分

还添加了一个新的 go_info_ext 仪表，包含 compiler、GOARCH 和 GOOS 标签，提供超出标准 go_info 指标的扩展构建环境信息。

受影响组件：vtgate、vttablet、vtctld、vtorc、vtbackup、mysqlctld

无需配置 — 指标会自动出现在使用 Prometheus 后端的所有组件的 /metrics 端点上。

<a id="次要变更-备份恢复"/>备份与恢复

<a id="mysql-clone-支持"/>MySQL CLONE 支持用于副本供应

VTTablet 和 VTBackup 现在支持使用 MySQL 原生 CLONE 插件通过网络直接从捐赠 Tablet 复制数据来供应新的副本。物理级别数据复制比逻辑备份和恢复快得多，特别是对于大型数据集。要求 MySQL 8.0.17+ 且仅支持 InnoDB 表。

新标志：

标志 描述
--mysql-clone-enabled 启用 MySQL CLONE 插件并在 MySQL 初始化期间创建克隆用户。所有将参与 CLONE 操作的 Tablet 都需要此标志。
--clone-from-primary 从分片的主 Tablet 克隆数据，而不是从备份恢复。与 --clone-from-tablet 互斥。
--clone-from-tablet 从特定 Tablet 按别名（例如 zone1-123）克隆数据，而不是从备份恢复。与 --clone-from-primary 互斥。
--restore-with-clone 在恢复阶段使用 MySQL CLONE，而不是从备份恢复。需要 --clone-from-primary 或 --clone-from-tablet 之一。
--clone-restart-wait-timeout 等待 CLONE REMOTE 完成后 MySQL 重启的超时时间。默认：5 分钟。

克隆用户配置：

标志 描述
--db-clone-user 用于 CLONE 操作的 MySQL 用户名（捐赠认证）。
--db-clone-password CLONE 用户的密码。
--db-clone-use-ssl 连接到捐赠者进行 CLONE 操作时使用 SSL。

示例用法：

从分片的主库克隆：

vttablet \\
  --mysql-clone-enabled \\
  --restore-with-clone \\
  --clone-from-primary \\
  ...

从特定 Tablet 克隆：

vtbackup \\
  --mysql-clone-enabled \\
  --restore-with-clone \\
  --clone-from-tablet=zone1-0000000100 \\
  ...

注意： 所有参与 CLONE 操作的 Tablet（捐赠者和接收者）都必须在 MySQL 初始化期间设置 --mysql-clone-enabled，以确保加载 CLONE 插件且克隆用户存在。

<a id="恢复钩子-备份引擎环境"/>恢复钩子改进

扩展钩子覆盖范围：vttablet_restore_done 钩子现在会在通过 vtctldclient RestoreFromBackup 触发恢复时触发。此前，此钩子仅在 Tablet 启动或克隆操作期间运行。

新环境变量：钩子现在设置 TM_RESTORE_DATA_BACKUP_ENGINE 以指示使用了哪个备份引擎。该值来自备份清单的 BackupMethod 字段。

TM_RESTORE_DATA_BACKUP_ENGINE 仅在恢复从实际备份读取时设置——不适用于基于克隆的恢复或未使用备份时。钩子脚本可以使用此变量根据恢复是使用 builtin、xtrabackup 还是其他引擎来执行特定于引擎的操作。

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

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

感谢所有贡献者：@ChaitanyaD48, @Devanshusharma2005, @MargaretMorehead, @anujagrawal380, @aparajon, @app/dependabot, @app/promptless, @app/vitess-bot, @arthurschreiber, @c-r-dev, @chengyuan, @connorolaya, @dasl-, @dbussink, @demmer, @derekperkins, @ejortegau, @esignorelli, @farhann-saleem, @frouioui, @ghostframe, @harshit-gangal, @jdoupe, @khkim6040, @lizztheblizz, @maksimov, @mattlord, @maxenglander, @mcpherrinm, @mcrauwel, @mhamza15, @nickvanw, @pourtorabehsan, @rjlaine, @rvrangel, @sbaker617, @shlomi-noach, @siddharth16396, @stefanb, @stutibiyani, @systay, @tanjinx, @tetsuro-ohyama, @timvaillancourt, @ttran397, @twthorn, @varundeepsaini, @vitess-bot, @yushuqin

更新内容 （原始）

Release of Vitess v24.0.0

Summary

Table of Contents

Major Changes

New Support

Window function pushdown for sharded keyspaces

This release introduces an optimization that allows window functions to be pushed down to individual shards when they are partitioned by a column that matches a unique vindex.

Previously, all window function queries required single-shard routing, which limited their applicability on sharded tables. With this change, queries where the PARTITION BY clause aligns with a unique vindex can now be pushed down and executed on each shard.

For examples and more details, see the documentation.

View Routing Rules

Vitess now supports routing rules for views, and can be applied the same as tables with vtctldclient ApplyRoutingRules. When a view routing rule is active, VTGate rewrites queries that reference the source view to use the target view’s definition instead. For example, given this routing rule:

{
  "rules": [
    {
      "from_table": "source_ks.my_view",
      "to_tables": ["target_ks.my_view"]
    }
  ]
}

And this view definition:

CREATE VIEW target_ks.my_view AS SELECT id, name FROM user;

A query like SELECT * FROM source_ks.my_view would be internally rewritten to:

SELECT * FROM (SELECT id, name FROM target_ks.user) AS my_view;

View routing rules require the schema tracker to monitor views, which means VTGate must be started with the --enable-views flag and VTTablet with the --queryserver-enable-views flag. The target view must exist in the specified keyspace for the routing rule to function correctly. For more details, see the Schema Routing Rules documentation.

Tablet targeting via USE statement

VTGate now supports routing queries to a specific tablet by alias using an extended USE statement syntax:

USE keyspace:shard@tablet_type|tablet_alias;

For example, to target a specific replica tablet:

USE commerce:-80@replica|zone1-0000000100;

Once set, all subsequent queries in the session route to the specified tablet until cleared with a standard USE keyspace or USE keyspace@tablet_type statement. This is useful for debugging, per-tablet monitoring, cache warming, and other operational tasks where targeting a specific tablet is required.

Note: A shard must be specified when using tablet targeting. Like shard targeting, this bypasses vindex-based routing, so use with care.

Binlog Streaming Support

VTGate now supports GTID-based binlog streaming through two protocols:

  • MySQL protocol: Clients can connect using the standard MySQL COM_BINLOG_DUMP_GTID replication protocol command—no special VStream-aware adapters or direct MySQL access required.
  • gRPC: The new BinlogDumpGTID streaming RPC in vtgateservice provides native gRPC access for custom clients without the MySQL protocol dependency.

Note: Only GTID-based streaming is supported. File/position-based streaming is not available through either COM_BINLOG_DUMP or COM_BINLOG_DUMP_GTID and returns an error.

This feature is disabled by default. Enable it with --enable-binlog-dump.

New flags:

  • --enable-binlog-dump: Enables binlog dump support. Without this flag, binlog dump requests return an error.
  • --binlog-dump-authorized-users: Comma-separated list of users authorized to execute binlog dump operations, or % to allow all users.

Requirements:

When initiating a binlog dump connection, clients must specify:

  • An empty filename
  • A file position (filepos) of 4
  • A GTID position

For gRPC clients, specify the keyspace, shard, and optionally the tablet type or tablet alias directly in the BinlogDumpGTIDRequest.

Limitations:

  • Each stream operates on a single tablet—no data aggregation across shards.
  • No automatic failover—if the targeted tablet becomes unavailable, the stream fails and the client must reconnect to a different tablet.
  • Not compatible with MoveTables or Reshard operations. Use the VStream API for those use cases.

Structured logging

Vitess now uses structured JSON logging by default. Log output is emitted as JSON to stderr. To configure the minimum log level, pass --log-level (one of debug, info, warn, error; default info). For a human-readable format with automatic color detection, pass --log-format=text. To revert to the previous glog backend, pass --log-structured=false.

glog is deprecated as of v24 and will be removed in v25.

Breaking Changes

External Decompressor No Longer Read from Backup MANIFEST by Default

The external decompressor command stored in a backup’s MANIFEST file is no longer used at restore time by default. Previously, when no --external-decompressor flag was provided, VTTablet would fall back to the command specified in the MANIFEST. This posed a security risk: an attacker with write access to backup storage could modify the MANIFEST to execute arbitrary commands on the tablet.

Starting in v24, the MANIFEST-based decompressor is ignored unless you explicitly opt in with the new --external-decompressor-use-manifest flag. If you rely on this behavior, add the flag to your VTTablet configuration, but be aware of the security implications.

See #19460 for details.

Minor Changes

VReplication

--shards flag for MoveTables/Reshard start and stop

The start and stop commands for MoveTables and Reshard workflows now support the --shards flag, allowing users to start or stop workflows on a specific subset of shards rather than all shards at once.

Example usage:

# Start workflow on specific shards only
vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer start --shards="-80,80-"

# Stop workflow on specific shards only
vtctldclient Reshard --target-keyspace customer --workflow cust2cust stop --shards="80-"

Automatic tablet retry for tablet-specific errors

VReplication workflows now automatically retry with different tablets when encountering tablet-specific errors. Previously, workflows without a cell preference would default to the local cell and could get stuck retrying the same failing tablet indefinitely.

When a tablet encounters errors like binary log purging (MySQL error 1236 or 1789) or GTID set mismatches, VReplication adds that tablet to an ignore list and tries other tablets across all cells. Once all matching tablets have been tried, the ignore list is cleared and the workflow retries from scratch.

This is particularly useful in multi-cell deployments where a tablet in the local cell may lack the required binary logs, but tablets in other cells still have them.

VTGate

Removed --grpc-send-session-in-streaming flag

The VTGate flag --grpc-send-session-in-streaming has been removed. This flag was deprecated in v22 via #17907 and defaulted to true.

The session is now always sent as the last packet in the streaming response for StreamExecute and StreamExecuteMulti RPCs. This behavior is required to support transactions in streaming and cannot be disabled.

Impact: Remove any usage of the --grpc-send-session-in-streaming flag from VTGate startup scripts or configuration.

New default for --legacy-replication-lag-algorithm flag

The VTGate flag --legacy-replication-lag-algorithm now defaults to false, disabling the legacy approach to handling replication lag by default.

Instead, a simpler algorithm purely based on low lag, high lag and minimum number of tablets is used, which has proven to be more stable in many production environments. A detailed explanation of the two approaches is explained in this code comment.

In v25 this flag will become deprecated and in the following release it will be removed. In the meantime, the legacy behaviour can be used by setting --legacy-replication-lag-algorithm=true. This deprecation is tracked in https://github.com/vitessio/vitess/issues/18914.

New “session” mode for --vtgate-balancer-mode flag

The VTGate flag --vtgate-balancer-mode now supports a new “session” mode in addition to the existing “cell”, “prefer-cell”, and “random” modes. Session mode routes each session consistently to the same tablet for the session’s duration.

To enable session mode, set the flag when starting VTGate:

--vtgate-balancer-mode=session

Query Serving

JSON_EXTRACT now supports dynamic path arguments

The JSON_EXTRACT function now supports dynamic path arguments like bind variables or results from other function calls. Previously, JSON_EXTRACT only worked with static string literals for path arguments.

NULL handling now matches MySQL behavior. The function returns NULL when either the document or path argument is NULL.

Static path arguments are still optimized, even when mixed with dynamic arguments, so existing queries won’t see any performance regression.

VTTablet

New Experimental flag --init-tablet-type-lookup

The new experimental flag --init-tablet-type-lookup for VTTablet allows tablets to automatically restore their previous tablet type on restart by looking up the existing topology record, rather than always using the static --init-tablet-type value.

When enabled, the tablet uses its alias to look up the tablet type from the existing topology record on restart. This allows tablets to maintain their changed roles (e.g., RDONLY/DRAINED) across restarts without manual reconfiguration. If disabled or if no topology record exists, the standard --init-tablet-type value will be used instead.

Note: Vitess Operator–managed deployments generally do not keep matching tablet records in the topo across pod replacements, so this feature will have a more limited effect in those environments.

QueryThrottler Observability Metrics

VTTablet now exposes new metrics to track QueryThrottler behavior.

Four new metrics have been added:

  • QueryThrottlerRequests: Total number of requests evaluated by the query throttler
  • QueryThrottlerThrottled: Number of requests that were throttled
  • QueryThrottlerTotalLatencyNs: Total time each request takes in query throttling, including evaluation, metric checks, and other overhead (in nanoseconds)
  • QueryThrottlerEvaluateLatencyNs: Time taken to make the throttling decision (in nanoseconds)

All metrics include labels for Strategy, Workload, and Priority. The QueryThrottlerThrottled metric has additional labels for MetricName, MetricValue, and DryRun to identify which metric triggered the throttling and whether it occurred in dry-run mode.

These metrics help monitor throttling patterns, identify which workloads are throttled, measure performance overhead, and validate behavior in dry-run mode before configuration changes.

QueryThrottler Event-Driven Configuration Updates

QueryThrottler configuration is now propagated to and stored in the SrvKeyspace record within the topology server and managed using standard topology tools. Previously, tablets polled for configuration changes every 60 seconds. Tablets now use event-driven watches (WatchSrvKeyspace) to receive updates immediately when the query throttling configuration changes. All tablets in a keyspace see configuration changes at roughly the same time, and topology server changes are versioned and auditable.

This change replaces the previous file-based configuration loader with a protobuf-defined configuration structure stored in the topology. The new configuration includes fields for enabling/disabling throttling, selecting the throttling strategy, and configuring strategy-specific rules.

Tablet Connection Pool Waiter Cap

VTTablet now allows users to set a limit on the number of requests waiting to get a connection from the connection pool, for the query, stream, and transaction connection pools. The limits are set with the following flags:

  • --queryserver-config-query-pool-waiter-cap
  • --queryserver-config-stream-pool-waiter-cap
  • --queryserver-config-txpool-waiter-cap

All of the above have a default value of 0, meaning no limit, thus preserving the behavior of the previous version.

Tracing

OpenTelemetry tracing support

Vitess now supports OpenTelemetry as a tracing backend. To use it, set --tracer opentelemetry on any Vitess binary. Traces are exported via OTLP/gRPC, configurable with the following flags:

  • --otel-endpoint: OpenTelemetry collector endpoint. If empty, the OTEL_EXPORTER_OTLP_ENDPOINT env var is used; if that is also unset, the OTel SDK defaults to localhost:4317.
  • --otel-insecure (default false): use insecure connection to the collector.
  • --tracing-sampling-rate (default 0.1): sampling rate for traces (shared across all tracing backends).

Any OTLP-compatible backend (Jaeger v1.35+, Grafana Tempo, Datadog Agent, etc.) can receive these traces.

Deprecation of OpenTracing-based tracing backends

The following tracing backends are deprecated as of v24 and will be removed in v25:

  • opentracing-jaeger — Uses the Jaeger client-go library, which has been archived. The Jaeger project recommends migrating to OpenTelemetry. Users should migrate to --tracer opentelemetry with an OTLP-compatible Jaeger endpoint (v1.35+).
  • opentracing-datadog — Uses the OpenTracing bridge in dd-trace-go. Users should migrate to --tracer opentelemetry with the Datadog Agent’s OTLP ingestion endpoint.

The --tracer opentracing-jaeger and --tracer opentracing-datadog options continue to work in v24 but will log a deprecation warning at startup. The following Jaeger-specific flags are also deprecated and will be removed in v25:

  • --jaeger-agent-host
  • --tracing-sampling-type

Migration: Replace --tracer opentracing-jaeger with --tracer opentelemetry and --jaeger-agent-host host:port with --otel-endpoint host:4317. Ensure your Jaeger deployment accepts OTLP (Jaeger v1.35+ listens on port 4317 by default).

VTOrc

New --cell Flag

VTOrc now supports a --cell flag that specifies which Vitess cell the VTOrc process is running in. The flag is optional in v24 but will be required in v25+, similar to VTGate’s --cell flag.

When provided, VTOrc validates that the cell exists in the topology service on startup. Without the flag, VTOrc logs a warning about the v25+ flag requirement.

This enables future cross-cell problem validation, where VTOrc will be able to ask another cell to validate detected problems before taking recovery actions. The flag is currently validated but not yet used in VTOrc recovery logic.

Note: If you’re running VTOrc in a multi-cell deployment, start using the --cell flag now to prepare for the v25 requirement.

Ordered Recovery Execution and Semi-Sync Rollout

VTOrc now executes recoveries per-shard with a defined ordering, rather than per-tablet in isolation. Problems that have ordering dependencies (e.g., semi-sync configuration) are executed serially first, while independent problems are executed concurrently. This ensures that dependent recoveries happen in the correct sequence within a shard.

The main user-facing improvement is for semi-sync rollouts: VTOrc now ensures replicas have semi-sync enabled before updating the primary. Previously, enabling semi-sync on the primary before enough replicas were ready could stall writes while the primary waited for semi-sync acknowledgements that no replica was prepared to send.

See #19427 for details.

Deprecated VTOrc Metric Removed

The DiscoverInstanceTimings metric has been removed from VTOrc in v24. This metric was deprecated in v23.

Migration: Use DiscoveryInstanceTimings instead, which provides the same timing information for instance discovery actions (Backend, Instance, Other).

Impact: Monitoring dashboards or alerting systems using DiscoverInstanceTimings must be updated to use DiscoveryInstanceTimings.

Deprecation of Snapshot Topology feature

VTOrc’s Snapshot Topology feature, which is enabled by setting --snapshot-topology-interval to a non-zero-value is deprecated as of v24 and the logic is planned for removal in v25.

The lack of facilities to read the snapshots created by this feature coupled with the in-memory nature of VTOrc’s backend means this logic has limited usefulness. This deprecation is explained and tracked in detail in https://github.com/vitessio/vitess/issues/18691.

Migration: remove the VTOrc flag --snapshot-topology-interval before v25.

Impact: VTOrc can no longer create snapshots of the topology in it’s backend database.

Deprecated /api/replication-analysis Endpoint Removed

The /api/replication-analysis endpoint has been removed from VTOrc in v24. Use /api/detection-analysis instead, which provides the same functionality.

Migration: Update any scripts, monitoring systems, or automation that calls /api/replication-analysis to use /api/detection-analysis instead. The replacement endpoint accepts the same query parameters (keyspace, shard) and returns the same JSON response format.

Impact: HTTP requests to /api/replication-analysis will return a 404 Not Found error.

Metrics

Extended Go Runtime Metrics via Prometheus

Vitess now exposes the full set of Go runtime metrics via Prometheus. The default Prometheus GoCollector only exposes three runtime/metrics (/gc/gogc:percent, /gc/gomemlimit:bytes, /sched/gomaxprocs:threads) plus the legacy go_memstats_* set. Starting in v24, all Vitess components expose approximately 150 additional metrics from Go’s runtime/metrics package.

New metrics include:

  • Heap allocation histograms
  • GC cycle counts and pause histograms
  • Memory class breakdowns
  • Goroutine state breakdowns
  • Scheduler latency histograms
  • CPU time breakdowns by class (user, GC, scavenge, idle)

A new go_info_ext gauge is also added with compiler, GOARCH, and GOOS labels, providing extended build environment information beyond the standard go_info metric.

Affected components: vtgate, vttablet, vtctld, vtorc, vtbackup, mysqlctld

No configuration required — the metrics appear automatically on the /metrics endpoint for all components using the Prometheus backend.

Backup and Restore

MySQL CLONE Support for Replica Provisioning

VTTablet and VTBackup now support using MySQL’s native CLONE plugin to provision new replicas by copying data directly from a donor tablet over the network. Physical-level data copying is significantly faster than logical backup and restore, especially for large datasets. Requires MySQL 8.0.17+ and InnoDB-only tables.

New Flags:

Flag Description
--mysql-clone-enabled Enable the MySQL CLONE plugin and create the clone user during MySQL initialization. Required for all tablets that will participate in CLONE operations.
--clone-from-primary Clone data from the shard’s primary tablet instead of restoring from backup. Mutually exclusive with --clone-from-tablet.
--clone-from-tablet Clone data from a specific tablet by alias (e.g., zone1-123) instead of restoring from backup. Mutually exclusive with --clone-from-primary.
--restore-with-clone Use MySQL CLONE for the restore phase instead of restoring from backup. Requires either --clone-from-primary or --clone-from-tablet.
--clone-restart-wait-timeout Timeout for waiting for MySQL to restart after CLONE REMOTE completes. Default: 5 minutes.

Clone User Configuration:

Flag Description
--db-clone-user MySQL username for CLONE operations (donor authentication).
--db-clone-password Password for the CLONE user.
--db-clone-use-ssl Use SSL when connecting to the donor for CLONE operations.

Example Usage:

Clone from the shard’s primary:

vttablet \
  --mysql-clone-enabled \
  --restore-with-clone \
  --clone-from-primary \
  ...

Clone from a specific tablet:

vtbackup \
  --mysql-clone-enabled \
  --restore-with-clone \
  --clone-from-tablet=zone1-0000000100 \
  ...

Note: All tablets participating in CLONE operations (both donors and recipients) must have --mysql-clone-enabled set during MySQL initialization to ensure the CLONE plugin is loaded and the clone user exists.

Restore Hook Improvements

Extended Hook Coverage: The vttablet_restore_done hook now fires when restores are triggered via vtctldclient RestoreFromBackup. Previously, this hook only ran during tablet startup or clone operations.

New Environment Variable: The hook now sets TM_RESTORE_DATA_BACKUP_ENGINE to indicate which backup engine was used. The value comes from the backup manifest’s BackupMethod field.

TM_RESTORE_DATA_BACKUP_ENGINE is only set when a restore reads from an actual backup—not for clone-based restores or when no backup is used. Hook scripts can use this to perform engine-specific actions based on whether the restore used builtin, xtrabackup, or another engine.

The entire changelog for this release can be found here.

The release includes 460 merged Pull Requests.

Thanks to all our contributors: @ChaitanyaD48, @Devanshusharma2005, @MargaretMorehead, @anujagrawal380, @aparajon, @app/dependabot, @app/promptless, @app/vitess-bot, @arthurschreiber, @c-r-dev, @chengyuan, @connorolaya, @dasl-, @dbussink, @demmer, @derekperkins, @ejortegau, @esignorelli, @farhann-saleem, @frouioui, @ghostframe, @harshit-gangal, @jdoupe, @khkim6040, @lizztheblizz, @maksimov, @mattlord, @maxenglander, @mcpherrinm, @mcrauwel, @mhamza15, @nickvanw, @pourtorabehsan, @rjlaine, @rvrangel, @sbaker617, @shlomi-noach, @siddharth16396, @stefanb, @stutibiyani, @systay, @tanjinx, @tetsuro-ohyama, @timvaillancourt, @ttran397, @twthorn, @varundeepsaini, @vitess-bot, @yushuqin

下载链接