Vitess v23.0.3

Release of Vitess v23.0.3

Summary

This is a security focused release. It contains fixes for two recently reported CVEs along with a number of other security related fixes.

External Decompressor No Longer Read from Backup MANIFEST by Default

This is a fix for the following security advisory and associated CVE

• Advisory: GHSA-8g8j-r87h-p36x
• CVE: https://www.cve.org/CVERecord?id=CVE-2026-27965

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.

Please note that this is a breaking change. Starting in v23.0.3, 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.

Prevent Path Traversals Via Backup MANIFEST Files On restore

This is a fix for the following security advisory and associated CVE

• Advisory: GHSA-r492-hjgh-c9gw
• CVE: https://www.cve.org/CVERecord?id=CVE-2026-27969

We now prevent a common Path Traversal attack that someone with write access to backup storage could use to escape the target restore directory and write files to arbitrary filesystem paths via modifications to the MANIFEST.

See #19470 for details.

---

The entire changelog for this release can be found here.

The release includes 22 merged Pull Requests.

Thanks to all our contributors: @app/vitess-bot, @bcremer, @mattlord

Vitess v22.0.4

Release of Vitess v22.0.4

Summary

This is a security focused release. It contains fixes for two recently reported CVEs along with a number of other security related fixes.

External Decompressor No Longer Read from Backup MANIFEST by Default

This is a fix for the following security advisory and associated CVE

• Advisory: GHSA-8g8j-r87h-p36x
• CVE: https://www.cve.org/CVERecord?id=CVE-2026-27965

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.

Please note that this is a breaking change. Starting in v22.0.4, 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.

Prevent Path Traversals Via Backup MANIFEST Files On restore

This is a fix for the following security advisory and associated CVE

• Advisory: GHSA-r492-hjgh-c9gw
• CVE: https://www.cve.org/CVERecord?id=CVE-2026-27969

We now prevent a common Path Traversal attack that someone with write access to backup storage could use to escape the target restore directory and write files to arbitrary filesystem paths via modifications to the MANIFEST.

See #19470 for details.

---

The entire changelog for this release can be found here.

The release includes 37 merged Pull Requests.

Thanks to all our contributors: @app/vitess-bot, @mattlord, @vitess-bot

Vitess v23.0.2

Release of Vitess v23.0.2

The entire changelog for this release can be found here.

The release includes 16 merged Pull Requests.

Thanks to all our contributors: @app/vitess-bot, @mattlord, @vitess-bot

Vitess v23.0.1

Release of Vitess v23.0.1

The entire changelog for this release can be found here.

The release includes 51 merged Pull Requests.

Thanks to all our contributors: @app/vitess-bot, @mattlord, @mhamza15, @systay, @timvaillancourt, @vitess-bot

Vitess v22.0.3

Release of Vitess v22.0.3

The entire changelog for this release can be found here.

The release includes 40 merged Pull Requests.

Thanks to all our contributors: @app/vitess-bot, @mattlord, @mhamza15, @timvaillancourt, @vitess-bot

Vitess v22.0.2

Release of Vitess v22.0.2

The entire changelog for this release can be found here.

The release includes 59 merged Pull Requests.

Thanks to all our contributors: @GuptaManan100, @app/vitess-bot, @arthurschreiber, @mattlord, @vitess-bot

Vitess v21.0.6

Release of Vitess v21.0.6

The entire changelog for this release can be found here.

The release includes 42 merged Pull Requests.

Thanks to all our contributors: @GuptaManan100, @app/vitess-bot, @arthurschreiber, @harshit-gangal, @mattlord

Vitess v23.0.0

Release of Vitess v23.0.0

Summary

Table of Contents

• Major Changes
  • Breaking Changes
  • Flag Naming Convention Migration
  • New default versions
    • Upgrade to MySQL 8.4
  • New Support
    • Multi-Query Execution
    • Transaction Timeout Session Variable
    • Experimental: Query Throttler
    • Multiple Lookup Vindexes Support
    • Reference Tables in Materialize Workflows
    • Online DDL Shard-Specific Completion
    • WITH RECURSIVE CTEs
    • CREATE TABLE ... SELECT Support
  • Deprecations
    • Metrics
    • CLI Flags
  • Deletions
    • Metrics
  • New Metrics
    • VTGate
    • VTTablet
    • VTOrc
• Minor Changes
  • New CLI Flags
    • VReplication/Materialize
    • Observability
    • VTOrc
    • Backup/Restore
    • CLI Tools
    • VTAdmin
    • VTGate
  • Modified Metrics
  • Parser/SQL Enhancements
  • Query Planning Improvements
  • Topology
    • --consul-auth-static-file requires 1 or more credentials
  • VTOrc
    • Aggregated Discovery Metrics HTTP API removed
    • Dynamic control of EmergencyReparentShard-based recoveries
    • Recovery stats to include keyspace/shard
    • /api/replication-analysis HTTP API deprecation
  • VTTablet
    • API Changes
    • CLI Flags
    • Managed MySQL configuration defaults to caching-sha2-password
    • MySQL timezone environment propagation
    • gRPC tabletmanager client error changes
  • Docker

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)

**Configuratio...

Vitess v23.0.0-rc2

Release of Vitess v23.0.0

Summary

Table of Contents

• Major Changes
  • New default versions
    • Upgrade to MySQL 8.4
• Minor Changes
  • Deprecations
    • Metrics
  • Deletions
    • Metrics
  • New Metrics
    • VTGate
    • VTOrc
  • Topology
    • --consul_auth_static_file requires 1 or more credentials
  • VTOrc
    • Aggregated Discovery Metrics HTTP API removed
    • Dynamic control of EmergencyReparentShard-based recoveries
    • Recovery stats to include keyspace/shard
    • /api/replication-analysis HTTP API deprecation
  • VTTablet
    • API Changes
    • CLI Flags
    • Managed MySQL configuration defaults to caching-sha2-password
    • MySQL timezone environment propagation
    • gRPC tabletmanager client error changes
  • Docker

Major Changes

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.

Minor Changes

Deprecations

Metrics

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

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

New Metrics

VTGate

Name	Dimensions	Description	PR
TransactionsProcessed	Shard, Type	Counts transactions processed at VTGate by shard distribution and transaction type.	#18171

VTOrc

Name	Dimensions	Description	PR
SkippedRecoveries	RecoveryName, Keyspace, Shard, Reason	Count of the different skipped recoveries processed.	#17985

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.

VTOrc

Aggregated Discovery Metrics HTTP API removed

VTOrc's undocumented /api/aggregated-discovery-metrics HTTP API endpoint was removed. 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 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 keyspace/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.

Recovery stats to include keyspace/shard

The following recovery-related stats now include labels for keyspaces and shards:

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

Previous to this release, only the recovery "type" was included in labels.

/api/replication-analysis HTTP API deprecation

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

VTTablet

API Changes

• Added RestartReplication method to TabletManagerClient interface. 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.

CLI Flags

• skip-user-metrics flag if enabled, replaces the username label with "UserLabelDisabled" to prevent metric explosion in environments with many unique users.

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. 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.
As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables.
⚠️ Deployments that relied on the old behav...

Vitess v23.0.0-rc1

Release of Vitess v23.0.0

Summary

Table of Contents

• Major Changes
  • New default versions
    • Upgrade to MySQL 8.4
• Minor Changes
  • Deprecations
    • Metrics
  • Deletions
    • Metrics
  • New Metrics
    • VTGate
    • VTOrc
  • Topology
    • --consul_auth_static_file requires 1 or more credentials
  • VTOrc
    • Aggregated Discovery Metrics HTTP API removed
    • Dynamic control of EmergencyReparentShard-based recoveries
    • Recovery stats to include keyspace/shard
    • /api/replication-analysis HTTP API deprecation
  • VTTablet
    • API Changes
    • CLI Flags
    • Managed MySQL configuration defaults to caching-sha2-password
    • MySQL timezone environment propagation
    • gRPC tabletmanager client error changes
  • Docker

Major Changes

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.

Minor Changes

Deprecations

Metrics

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

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

New Metrics

VTGate

Name	Dimensions	Description	PR
TransactionsProcessed	Shard, Type	Counts transactions processed at VTGate by shard distribution and transaction type.	#18171

VTOrc

Name	Dimensions	Description	PR
SkippedRecoveries	RecoveryName, Keyspace, Shard, Reason	Count of the different skipped recoveries processed.	#17985

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.

VTOrc

Aggregated Discovery Metrics HTTP API removed

VTOrc's undocumented /api/aggregated-discovery-metrics HTTP API endpoint was removed. 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 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 keyspace/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.

Recovery stats to include keyspace/shard

The following recovery-related stats now include labels for keyspaces and shards:

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

Previous to this release, only the recovery "type" was included in labels.

/api/replication-analysis HTTP API deprecation

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

VTTablet

API Changes

• Added RestartReplication method to TabletManagerClient interface. 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.

CLI Flags

• skip-user-metrics flag if enabled, replaces the username label with "UserLabelDisabled" to prevent metric explosion in environments with many unique users.

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. 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.
As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables.
⚠️ Deployments that relied on the old behav...