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

Vitess v24.0.0 版本引入了多项重要更新。主要变化包括支持分片键空间的窗口函数下推优化、视图路由规则以及通过 USE 语句将查询路由至特定 tablet。一个破坏性变更是备份清单中的外部解压命令默认不再读取，需通过新标志显式启用。

次要改进涵盖多个方面：VTGate 新增了基于 GTID 的 binlog 流支持；VTOrc 引入了 –cell 标志、改进了恢复执行顺序并移除了废弃的 API 端点；VTTablet 增强了查询节流器的可观测性指标，并支持事件驱动的配置更新。此外，查询服务支持 JSON_EXTRACT 的动态路径参数，追踪功能现兼容 OpenTelemetry，并扩展了通过 Prometheus 暴露的 Go 运行时指标。备份恢复方面新增了 MySQL CLONE 插件支持，以加速副本配置。其他改进还包括结构化日志、连接池等待上限设置以及 tablet 关闭时的连接验证等。本版本合并了 436 个拉取请求，感谢所有贡献者。

更新内容（中文）

Vitess v24.0.0 发布

摘要

主要变更

新增支持

分片键空间的窗口函数下推

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

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

有关示例和更多详细信息，请参阅文档。

视图路由规则

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;

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

通过 USE 语句指定平板

VTGate 现在支持通过扩展的 USE 语句语法，使用别名将查询路由到特定平板：

USE keyspace:shard@tablet_type|tablet_alias;

例如，要指定特定的副本平板：

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

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

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

重大变更

外部解压命令默认不再从备份 MANIFEST 中读取

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

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

详见 #19460。

次要变更

日志

结构化日志

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

从 v24 开始 glog 已弃用，并将在 v25 中移除。

VReplication

`--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-\"

针对平板特定错误的自动重试

VReplication 工作流现在在遇到平板特定错误时会自动使用不同的平板进行重试。之前，没有单元偏好设置的工作流将默认使用本地单元，并可能陷入无限期重试同一个失败平板的困境。

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

这在多单元部署中特别有用，因为本地单元中的平板可能缺少所需的二进制日志，而其他单元中的平板仍然拥有它们。

VTGate

移除 `--grpc-send-session-in-streaming` 标志

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

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

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

`--legacy-replication-lag-algorithm` 标志的新默认值

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

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

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

`--vtgate-balancer-mode` 标志的新增 “session” 模式

VTGate 标志 --vtgate-balancer-mode 现在在现有的 “cell”、“prefer-cell” 和 “random” 模式之外，支持一个新的 “session” 模式。会话模式将在会话持续期间将每个会话始终路由到同一个平板。

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

--vtgate-balancer-mode=session

Binlog 流式传输支持

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

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

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

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

新标志：

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

要求：

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

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

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

限制：

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

查询服务

JSON_EXTRACT 现在支持动态路径参数

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

现在空值处理与 MySQL 行为一致。当文档或路径参数为 NULL 时，该函数返回 NULL。

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

VTTablet

新增实验性标志 `--init-tablet-type-lookup`

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

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

注意：Vitess Operator 管理的部署通常不会在重启之间保留 topo 中的平板记录，因此此功能在这些环境中不会生效。

QueryThrottler 可观测性指标

VTTablet 现在公开了跟踪 QueryThrottler 行为的新指标。

新增四个指标：

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

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

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

QueryThrottler 事件驱动配置更新

QueryThrottler 配置现在存储在拓扑服务器的 SrvKeyspace 中，并使用标准拓扑工具进行管理。之前，平板每 60 秒轮询一次配置更改。平板现在使用事件驱动的监视器 (WatchSrvKeyspace) 来在限流配置更改时立即接收更新。键空间中的所有平板几乎同时看到配置更改，并且拓扑服务器更改是版本化的且可审计。

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

OnlineDDL 输出中的新 `in_order_completion_pending_count` 字段

OnlineDDL 迁移输出现在包含一个新的 in_order_completion_pending_count 字段。使用 --in-order-completion 标志时，此字段显示在当前迁移完成之前必须完成多少个迁移。该字段在 SHOW vitess_migrations 查询和 vtctldclient OnlineDDL <db> show 输出中可见。

这提供了对迁移队列依赖关系的更好可见性，使得更容易理解为什么某个迁移可能被推迟。该计数在调度器循环期间自动更新，并在迁移完成、失败或取消时清除。

平板关闭跟踪与连接验证

Vitess 现在跟踪平板何时干净地关闭，并在尝试连接之前验证平板记录，从而减少不必要的连接尝试和日志噪音。

新字段：Tablet protobuf 中添加了一个新的 tablet_shutdown_time 字段。当平板干净关闭时，此字段设置为当前时间戳，并在平板启动时清除（设置为 nil）。这允许其他 Vitess 组件检测平板何时被有意离线。

连接验证：当平板记录设置了 tablet_shutdown_time 时，Vitess 组件将跳过连接尝试并返回指示平板已关闭的错误。VTOrc 现在将跳过轮询设置了 tablet_shutdown_time 的平板。对于非正常关闭（崩溃、被杀死等）的平板，该字段保持 nil，并保留 v24 之前的行为（带错误日志记录的连接尝试）。

注意：这是一种尽力而为的机制。被杀死或崩溃的平板可能没有机会设置此字段，在这种情况下，组件将继续像 v23 及更早版本那样尝试连接。

平板连接池等待者上限

VTTablet 现在允许为查询、流式处理和事务连接池设置等待从连接池获取连接的请求上限。限制通过以下标志设置：

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

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

跟踪

OpenTelemetry 跟踪支持

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

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

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

弃用基于 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）。

VTOrc

新增 `--cell` 标志

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

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

这为未来的跨单元问题验证奠定了基础，VTOrc 将能够请求另一个单元在采取恢复操作之前验证检测到的问题。该标志当前已被验证，但尚未在 VTOrc 恢复逻辑中使用。

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

改进的 VTOrc 发现日志

VTOrc 的 DiscoverInstance 函数现在在所有日志消息中包含平板别名，并在发生错误时使用正确的日志级别。之前，错误消息未指明哪个平板发现失败，并且错误以 INFO 级别而不是 ERROR 级别记录。

此改进使得在发现操作失败时更容易识别和调试特定平板的问题。

有序恢复执行与半同步部署

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

主要面向用户的改进是半同步部署：VTOrc 现在在更新主库之前确保副本已启用半同步。之前，在足够副本准备好之前在主库上启用半同步，可能会在主库等待副本未准备好发送的半同步确认时导致写入停滞。

详见 #19427。

已弃用的 VTOrc 指标已移除

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

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

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

快照拓扑功能已弃用

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

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

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

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

已弃用的 `/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 未找到错误。

指标

通过 Prometheus 扩展 Go 运行时指标

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

新指标包括：

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

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

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

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

备份与恢复

MySQL CLONE 支持用于副本配置

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

新标志：

标志	描述
`--mysql-clone-enabled`	启用 MySQL CLONE 插件并在 MySQL 初始化期间创建克隆用户。所有将参与 CLONE 操作的平板都必需。
`--clone-from-primary`	从分片的主平板克隆数据，而不是从备份恢复。与 `--clone-from-tablet` 互斥。
`--clone-from-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 \\
  ...

从特定平板克隆：

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

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

恢复钩子改进

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

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

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

更新内容（原始）

Release of Vitess v24.0.0

Summary

Major Changes
- New Support
- Breaking Changes
  - External Decompressor No Longer Read from Backup MANIFEST by Default
Minor Changes

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.

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

Logging

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.

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

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 command—no special VStream-aware adapters or direct MySQL access required.
gRPC: The new BinlogDumpGTID streaming RPC in vtgateservice.proto 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.

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 tablet records in the topo between restarts, so this feature will not take 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 (nanoseconds)
QueryThrottlerEvaluateLatencyNs: Time taken to make the throttling decision (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 stored in SrvKeyspace 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 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.

New `in_order_completion_pending_count` field in OnlineDDL outputs

OnlineDDL migration outputs now include a new in_order_completion_pending_count field. When using the --in-order-completion flag, this field shows how many migrations must complete before the current migration. The field is visible in SHOW vitess_migrations queries and vtctldclient OnlineDDL <db> show outputs.

This provides better visibility into migration queue dependencies, making it easier to understand why a migration might be postponed. The count is automatically updated during the scheduler loop and cleared when migrations complete, fail, or are cancelled.

Tablet Shutdown Tracking and Connection Validation

Vitess now tracks when tablets cleanly shut down and validates tablet records before attempting connections, reducing unnecessary connection attempts and log noise.

New Field: A new tablet_shutdown_time field has been added to the Tablet protobuf. This field is set to the current timestamp when a tablet cleanly shuts down and is cleared (set to nil) when the tablet starts. This allows other Vitess components to detect when a tablet is intentionally offline.

Connection Validation: When a tablet record has tablet_shutdown_time set, Vitess components will skip connection attempts and return an error indicating the tablet is shutdown. VTOrc will now skip polling tablets that have tablet_shutdown_time set. For tablets that shutdown uncleanly (crashed, killed, etc.), the field remains nil and the pre-v24 behavior is preserved (connection attempt with error logging).

Note: This is a best-effort mechanism. Tablets that are killed or crash may not have the opportunity to set this field, in which case components will continue to attempt connections as they did in v23 and earlier.

Tablet Connection Pool Waiter Cap

VTTablet now allows 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.

Improved VTOrc Discovery Logging

VTOrc’s DiscoverInstance function now includes the tablet alias in all log messages and uses the correct log level when errors occur. Previously, error messages did not indicate which tablet failed discovery, and errors were logged at INFO level instead of ERROR level.

This improvement makes it easier to identify and debug issues with specific tablets when discovery operations fail.

Ordered Recovery Execution and Semi-Sync Rollout

VTOrc now executes recoveries per-shard with 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 to 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 436 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

更新内容 （中文）

Vitess v24.0.0 发布

摘要

目录

更新内容 （原始）

Release of Vitess v24.0.0

Summary

Table of Contents

下载链接

相关文章

最近文章

友情链接

其它

更新内容（中文）

更新内容（原始）