vitess 23.0.0

[BrewTestBot]

Created by brew bump

---

Created with brew bump-formula-pr.

Details

release notes

# 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:

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

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


New Support
Multi-Query Execution
Vitess v23.0.0 introduces native support for executing multiple queries in a single RPC call through new ExecuteMulti and StreamExecuteMulti APIs (PR #18059).
This feature provides more efficient batch query execution without requiring manual query splitting or multiple round trips.
Usage Example:
queries := []string{
    "SELECT * FROM users WHERE id = 1",
    "SELECT * FROM orders WHERE user_id = 1",
    "SELECT * FROM payments WHERE user_id = 1",
}
results, err := vtgateConn.ExecuteMulti(ctx, queries)
Configuration: Enable with the --mysql-server-multi-query-protocol flag on VTGate.
Transaction Timeout Session Variable
A new transaction_timeout session variable has been added (PR #18560), allowing per-session control over transaction timeout duration.
Usage:
-- Set transaction timeout to 30 seconds for this session
SET transaction_timeout = 30;

-- Begin a transaction that will automatically rollback if not committed within 30s
BEGIN;
-- ... perform operations ...
COMMIT;
This provides more granular timeout control compared to global server settings, useful for:

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

Experimental: Query Throttler
Vitess v23.0.0 introduces a new, experimental Query Throttler framework for rate-limiting incoming queries (RFC issue #18412, PR #18449, PR #18657). Work on this new throttler is ongoing with the potential for breaking changes in the future.
Feedback on this experimental feature is appreciated in GitHub issues or the #feat-handling-overload channel of the Vitess Community Slack.
Features:

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

Configuration:

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

Dry-run Mode: Test throttling rules without actually blocking queries, useful for validating configuration before enforcement.
Multiple Lookup Vindexes Support
Creating multiple lookup vindexes in a single workflow is now supported through the --params-file flag (PR #17566).
Usage:
# Create multiple lookup vindexes from JSON configuration
vtctldclient LookupVindexCreate \
  --workflow my_lookup_workflow \
  --params-file /path/to/params.json \
  commerce
params.json example:
{
  "vindexes": [
    {
      "name": "user_email_lookup",
      "type": "consistent_lookup_unique",
      "table_owner": "users",
      "table_owner_columns": ["email"]
    },
    {
      "name": "user_name_lookup",
      "type": "consistent_lookup",
      "table_owner": "users",
      "table_owner_columns": ["name"]
    }
  ]
}
This significantly improves workflow efficiency when setting up multiple vindexes, reducing the number of separate operations required.
Reference Tables in Materialize Workflows
Reference tables can now be added to existing materialize workflows using the new Materialize ... update sub-command (PR #17804).
Usage:
# Add reference tables to an existing workflow
vtctldclient Materialize --workflow my_workflow update \
  --add-reference-tables ref_table1,ref_table2 \
  --target-keyspace my_keyspace
Use Case: Incrementally add reference tables to running materialize workflows without recreating the entire workflow, improving operational flexibility.
Online DDL Shard-Specific Completion
Online DDL migrations can now be completed on a per-shard basis using the new COMPLETE VITESS_SHARDS syntax (PR #18331).
Usage:
-- Complete migration on specific shards only
ALTER VITESS_MIGRATION '9e8a9249_3976_11ed_9442_0a43f95f28a3'
  COMPLETE VITESS_SHARDS '-80,80-';

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

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

WITH RECURSIVE CTEs
Vitess now supports WITH RECURSIVE common table expressions (PR #18590), enabling recursive queries for hierarchical data.
Example:
-- Find all employees in a management hierarchy
WITH RECURSIVE employee_hierarchy AS (
    SELECT id, name, manager_id, 1 as level
    FROM employees
    WHERE manager_id IS NULL

    UNION ALL

    SELECT e.id, e.name, e.manager_id, eh.level + 1
    FROM employees e
    INNER JOIN employee_hierarchy eh ON e.manager_id = eh.id
)
SELECT * FROM employee_hierarchy ORDER BY level, name;
This is a major SQL compatibility enhancement for applications with hierarchical or graph-like data structures.
CREATE TABLE ... SELECT Support
The SQL parser now supports CREATE TABLE ... SELECT statements (PR #18443), improving MySQL compatibility.
Example:
-- Create a table from a query result
CREATE TABLE recent_orders
SELECT * FROM orders
WHERE order_date > DATE_SUB(NOW(), INTERVAL 30 DAY);

Deprecations
Metrics



Component
Metric Name
Notes
Deprecation PR




vtorc
DiscoverInstanceTimings
Replaced by DiscoveryInstanceTimings
#18406



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

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

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

Deletions
Metrics



Component
Metric Name
Was Deprecated In
Deprecation PR




vtgate
QueriesProcessed
v22.0.0
#17727


vtgate
QueriesRouted
v22.0.0
#17727


vtgate
QueriesProcessedByTable
v22.0.0
#17727


vtgate
QueriesRoutedByTable
v22.0.0
#17727



See Breaking Changes for migration guidance.

New Metrics
VTGate



Name
Dimensions
Description
PR




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


OptimizedQueryExecutions
N/A
Counter tracking queries that used deferred optimization execution path.
#18067



Transaction Types in TransactionsProcessed:

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

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

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

VTTablet



Name
Dimensions
Description
PR




OnlineDDLStaleMigrationMinutes
N/A
Minutes since the oldest pending/ready migration was submitted.
#18417


vttablet_tablet_server_state
type, keyspace, shard
Enhanced with additional dimensions for better observability.
#18451



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



Name
Dimensions
Description
PR




SkippedRecoveries
RecoveryName, Keyspace, Shard, Reason
Count of skipped recoveries with reason tracking.
#18644


EmergencyReparentShardDisabled
Keyspace, Shard
Gauge indicating if ERS is disabled per keyspace/shard.
#17985



Use Case for EmergencyReparentShardDisabled: Create alerts to ensure EmergencyReparentShard-based recoveries are not disabled for an undesired period, maintaining high availability posture.
SkippedRecoveries Reasons: The Reason dimension tracks why recoveries were skipped (e.g., "ERSDisabled", "ReplicationLagHigh", "NotEnoughReplicas"), providing actionable insights for operational troubleshooting.

Minor Changes
New CLI Flags
VReplication/Materialize



Flag
Component
Description
PR




--params-file
vtctldclient
JSON file containing lookup vindex parameters for creating multiple lookup vindexes in a single workflow. Mutually exclusive with --type, --table-owner, and --table-owner-columns.
#17566


--add-reference-tables
vtctldclient
Comma-separated list of reference tables to add to an existing materialize workflow using the update sub-command.
#17804



Observability



Flag
Component
Description
PR




--skip-user-metrics
vttablet
If enabled, replaces the username label in user-based metrics with "UserLabelDisabled" to prevent metric cardinality explosion in environments with many unique users.
#18085


--querylog-emit-on-any-condition-met
vtgate, vttablet, vtcombo
Changes query log emission to emit when ANY logging condition is met (row-threshold, time-threshold, filter-tag, or error) rather than requiring ALL conditions. Default: false.
#18546


--querylog-time-threshold
vtgate, vttablet
Duration threshold for query logging. Queries exceeding this duration will be logged. Works with --querylog-emit-on-any-condition-met.
#18520


--grpc-enable-orca-metrics
vtgate, vttablet
Enable ORCA (Open Request Cost Aggregation) backend metrics reporting via gRPC for load balancing decisions. Default: false.
#18282


--datadog-trace-debug-mode
All components
Makes Datadog trace debug mode configurable instead of always-on. Default: false.
#18347



VTOrc



Flag
Component
Description
PR




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



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

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

Backup/Restore



Flag
Component
Description
PR




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



CLI Tools



Flag
Component
Description
PR




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



Example:
# Generate shard ranges with 4 hex characters
vtctldclient GenerateShardRanges --shards 16 --chars 4
# Output: -1000,1000-2000,2000-3000,...,f000-
VTAdmin
Five new TLS-related flags were added for secure vtctld connections (PR #18556):



Flag
Description




--vtctld-grpc-ca
CA certificate file for vtctld gRPC TLS


--vtctld-grpc-cert
Client certificate file for vtctld gRPC TLS


--vtctld-grpc-key
Client key file for vtctld gRPC TLS


--vtctld-grpc-server-name
Server name for vtctld gRPC TLS validation


--vtctld-grpc-crl
Certificate revocation list for vtctld gRPC TLS



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



Flag
Component
Description
PR




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




Modified Metrics
VTOrc Recovery Metrics Enhanced with Keyspace/Shard Labels
The following VTOrc recovery metrics now include Keyspace and Shard labels in addition to the existing RecoveryType label (PR #18304):

FailedRecoveries
PendingRecoveries
RecoveriesCount
SuccessfulRecoveries

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

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

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

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

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

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


Parser/SQL Enhancements
Vitess v23.0.0 includes significant SQL parser improvements for better MySQL compatibility:
New SQL Syntax Support



Feature
Description
PR




CREATE TABLE ... SELECT
Full support for creating tables from SELECT query results
#18443


WITH RECURSIVE
Recursive common table expressions for hierarchical queries
#18590


SET NAMES binary
Support for binary character set specification
#18582


ALTER VITESS_MIGRATION ... POSTPONE COMPLETE
Syntax for postponing Online DDL migration completion
#18118


VALUE keyword in INSERT/REPLACE
Support for VALUE (singular) in addition to VALUES
#18116



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

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

Operator Precedence Fixes

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


Query Planning Improvements
Window Functions in Single-Shard Queries
Window functions can now be pushed down to single-shard queries (PR #18103), improving performance for analytics workloads.
Before v23: Window functions were always executed at VTGate level, even for single-shard queries.
After v23: Window functions are pushed down when the query targets a single shard, reducing data transfer and improving performance.
Example:
-- This query now executes entirely on the target shard
SELECT
    user_id,
    order_date,
    amount,
    SUM(amount) OVER (PARTITION BY user_id ORDER BY order_date) as running_total
FROM orders
WHERE user_id = 12345;  -- Single-shard query
UNION Query Merging Improvements
UNION query optimization has been significantly enhanced (PR #18289, PR #18393):
Extended UNION Merging: UNION queries with Equal and IN opcodes can now be merged more aggressively, generating simpler SQL.
Derived Table Elimination: Unnecessary derived table wrapping is avoided for UNION queries, producing cleaner and more efficient SQL.
Example:
-- Query:
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;

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

-- After v23: Direct UNION (simpler, more efficient)
SELECT * FROM t1 WHERE id = 1
UNION
SELECT * FROM t1 WHERE id = 2;
Multi-Shard Read-Only Transactions in SINGLE Mode
Read-only transactions can now span multiple shards when using SINGLE transaction mode (PR #18173).
Before v23: SINGLE mode restricted all transactions to single shards, even read-only ones.
After v23: Read-only transactions can access multiple shards in SINGLE mode, improving flexibility without sacrificing consistency guarantees.
Impact: Applications using SINGLE transaction mode can now perform multi-shard read queries within transactions without needing to upgrade to MULTI or TWOPC modes.
Deferred Optimization for Prepared Statements
Prepared statements now support deferred optimization (PR #18126), allowing preparation to succeed even when plan generation requires runtime values.
Benefits:

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

Behavior: When a prepared statement cannot be fully optimized at preparation time, optimization is deferred to execution time when bind variable values are available.
Query Buffering for INSTANT DDL
Query buffering has been implemented for INSTANT DDL operations (PR #17945), reducing query failures during schema changes.
Features:

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

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

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

View the full release notes at https://github.com/vitessio/vitess/releases/tag/v23.0.0.

---

[github-actions]

🤖 An automated task has requested bottles to be published to this PR.

Caution

Please do not push to this PR branch before the bottle commits have been pushed, as this results in a state that is difficult to recover from. If you need to resolve a merge conflict, please use a merge commit. Do not force-push to this PR branch.