vtgate: add VEXPLAIN MYSQLPLAN statement

changelog/25.0/25.0.0/summary.md

@@ -28,6 +28,7 @@
         - [Preparing a statement no longer starts an implicit transaction](#vtgate-prepare-no-implicit-tx)
         - [Stricter validation of SQL-level PREPARE statements](#vtgate-prepare-stricter-validation)
         - [Stricter PROXY protocol v1 header validation](#vtgate-proxy-protocol-v1-strictness)
+        - [New `VEXPLAIN MYSQLPLAN` statement](#vtgate-vexplain-mysqlplan)
     - **[Reparent](#minor-changes-reparent)**
         - [`EmergencyReparentShard` no longer waits on replicas that cannot win the election](#ers-lagging-relay-log-wait)
         - [Reparent candidate ordering now respects partially ordered GTID histories](#reparent-gtid-candidate-ordering)
@@ -267,6 +268,14 @@ Specification-conformant v1 headers, as emitted by HAProxy, AWS load balancers,
 
 See [#20733](https://github.com/vitessio/vitess/pull/20733) for details.
 
+#### <a id="vtgate-vexplain-mysqlplan"/>New `VEXPLAIN MYSQLPLAN` statement</a>
+
+A new `VEXPLAIN MYSQLPLAN <query>` statement runs MySQL's `EXPLAIN FORMAT=JSON` against the shards a `SELECT` would target, **without executing the query itself**. It resolves each `Route`'s target shards from its vindex at resolution time and issues `EXPLAIN` against every resolved shard, attaching the per-shard MySQL plan to the VTGate plan tree keyed by shard, so per-shard plan and cost differences are visible.
+
+Unlike `VEXPLAIN ALL`, which executes the query to discover the shard-level queries before explaining them, `VEXPLAIN MYSQLPLAN` never runs the wrapped query.
+
+Only `SELECT` statements whose target shards can be resolved from a vindex without reading cluster data are supported. DML (`INSERT`/`UPDATE`/`DELETE`), and any query whose shard set depends on data — cross-shard joins, subqueries, and lookup vindexes — are rejected with an error suggesting `VEXPLAIN ALL` instead.
+
 ### <a id="minor-changes-reparent"/>Reparent</a>
 
 #### <a id="ers-lagging-relay-log-wait"/>`EmergencyReparentShard` no longer waits on replicas that cannot win the election</a>

go/test/endtoend/vtgate/queries/vexplain/vexplain_test.go

@@ -18,13 +18,16 @@ package vexplain
 
 import (
 	"fmt"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"vitess.io/vitess/go/mysql"
+	"vitess.io/vitess/go/mysql/capabilities"
 	"vitess.io/vitess/go/sqltypes"
+	"vitess.io/vitess/go/test/endtoend/onlineddl"
 	"vitess.io/vitess/go/test/endtoend/utils"
 )
 
@@ -149,3 +152,43 @@ func TestVExplainAll(t *testing.T) {
 	utils.AssertMatchesContains(t, conn, `vexplain /*vt+ EXECUTE_DML_QUERIES */ all insert into user (id,lookup,lookup_unique) values (4,'apa','foo'),(5,'apa','bar'),(6,'monkey','nobar')`, "Insert", "mysql_explain_json")
 	utils.AssertMatchesContains(t, conn, `vexplain all select id from user where lookup = "apa"`, "mysql_explain_json", "ByDestination")
 }
+
+func TestVExplainMySQLPlan(t *testing.T) {
+	// VEXPLAIN MYSQLPLAN is a v25 syntax; an older vtgate cannot parse it. Under the
+	// upgrade/downgrade CI this suite can run current test code against an N-1 vtgate.
+	utils.SkipIfBinaryIsBelowVersion(t, 25, "vtgate")
+
+	conn, closer := start(t)
+	defer closer()
+
+	// The result must carry the VTGate plan tree (Route) with real per-shard MySQL
+	// EXPLAIN output attached, without executing the query.
+	utils.AssertMatchesContains(t, conn,
+		`vexplain mysqlplan select id from user where id = 1`,
+		"mysql_explain_json", "Route")
+
+	// query_block is a key emitted only by a genuine MySQL EXPLAIN FORMAT=JSON, so it
+	// proves we actually reached MySQL. MariaDB's EXPLAIN JSON does not use it, so gate
+	// this assertion to MySQL/Percona 8.0+ (which covers the 8.0 and 8.4 CI flavors).
+	mysqlVersion := onlineddl.GetMySQLVersion(t, clusterInstance.Keyspaces[0].Shards[0].PrimaryTablet())
+	require.NotEmpty(t, mysqlVersion)
+	atLeast80, err := capabilities.ServerVersionAtLeast(mysqlVersion, 8, 0, 0)
+	require.NoError(t, err)
+	if atLeast80 && !strings.Contains(mysqlVersion, "MariaDB") {
+		utils.AssertMatchesContains(t, conn,
+			`vexplain mysqlplan select id from user where id = 1`,
+			"query_block")
+	}
+
+	// DML is not supported (its plans are not Route primitives): it must fail closed
+	// and point the user to VEXPLAIN ALL, not silently produce a plan with no EXPLAIN.
+	utils.AssertContainsError(t, conn,
+		`vexplain mysqlplan insert into user (id,lookup,lookup_unique) values (99,'apa','apa')`,
+		"use VEXPLAIN ALL instead")
+
+	// A lookup vindex cannot resolve shards without executing, so it must fail closed
+	// and point the user to VEXPLAIN ALL.
+	utils.AssertContainsError(t, conn,
+		`vexplain mysqlplan select id from user where lookup_unique = "apa"`,
+		"use VEXPLAIN ALL instead")
+}

go/vt/sqlparser/ast_funcs.go

@@ -2136,6 +2136,8 @@ func (ty VExplainType) ToString() string {
 		return TraceStr
 	case KeysVExplainType:
 		return KeysStr
+	case MySQLVExplainType:
+		return MySQLStr
 	default:
 		return "Unknown VExplainType"
 	}

go/vt/sqlparser/constants.go

@@ -299,6 +299,7 @@ const (
 	PlanStr        = "plan"
 	TraceStr       = "trace"
 	KeysStr        = "keys"
+	MySQLStr       = "mysqlplan"
 
 	// Lock Types
 	ReadStr             = "read"
@@ -864,6 +865,7 @@ const (
 	AllVExplainType
 	TraceVExplainType
 	KeysVExplainType
+	MySQLVExplainType
 )
 
 // Constant for Enum Type - SelectIntoType

go/vt/sqlparser/keywords.go

@@ -474,6 +474,7 @@ var keywords = []keyword{
 	{"multipoint", MULTIPOINT},
 	{"multipolygon", MULTIPOLYGON},
 	{"month", MONTH},
+	{"mysqlplan", MYSQLPLAN},
 	{"mysql_errno", MYSQL_ERRNO},
 	{"name", NAME},
 	{"names", NAMES},

go/vt/sqlparser/parse_test.go

@@ -2802,6 +2802,8 @@ var validSQL = []struct {
 	input: "vexplain trace select * from t",
 }, {
 	input: "vexplain keys select * from t",
+}, {
+	input: "vexplain mysqlplan select * from t",
 }, {
 	input: "explain analyze select * from t",
 }, {