Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
refactor(sql): build EXPLAIN statements in the parsers (#21485)
Danny Xub52c24c95579
diff --git a/backend/api/v1/query_result_masker.go b/backend/api/v1/query_result_masker.goindex 6f46dcca67..a9f841c833 100644--- a/backend/api/v1/query_result_masker.go+++ b/backend/api/v1/query_result_masker.go@@ -2,7 +2,6 @@ package v1import ("context"- "strings"metadatapb "github.com/bytebase/omni/metadata""github.com/pkg/errors"@@ -53,7 +52,8 @@ func (s *QueryResultMasker) MaskResults(ctx context.Context, spans []*parserbase// We expect the len(spans) == len(results), but to avoid NPE, we use the min(len(spans), len(results)) here.loopBoundary := min(len(spans), len(results))for i := 0; i < loopBoundary; i++ {- if strings.HasPrefix(strings.TrimSpace(results[i].Statement), "EXPLAIN") {+ // A plan is not row data, so it has no columns to trace to a masking policy.+ if parserbase.StartsWithExplain(results[i].Statement) {continue}if results[i].Error == "" && spans[i].FunctionNotSupportedError != nil {diff --git a/backend/api/v1/sql_service.go b/backend/api/v1/sql_service.goindex f7dc80ff3d..12a4885666 100644--- a/backend/api/v1/sql_service.go+++ b/backend/api/v1/sql_service.go@@ -2029,19 +2029,24 @@ func validateExplainFormat(engine storepb.Engine, format v1pb.QueryOption_Explaireturn connect.NewError(connect.CodeInvalidArgument, errors.Errorf("%s does not support explain format %s, supported formats: %s", engine, format, strings.Join(names, ", ")))}-// validateExplainStatements refuses an explain request whose EXPLAIN-wrapped form-// would execute a write. The driver splits a multi-statement request and prefixes-// EXPLAIN to each statement (see pg.go and its siblings), so this validates the-// same per-statement wrapped form: a smuggled "ANALYZE DELETE FROM t" becomes-// EXPLAIN ANALYZE DELETE and is rejected before it runs. Engines whose EXPLAIN is-// not a statement prefix (Oracle EXPLAIN PLAN, SQL Server SHOWPLAN, Spanner/BigQuery-// plan APIs) report ok=false from db.ExplainStatement and run their own plan API,-// which does not execute the statement.+// validateExplainStatements refuses an explain request whose planned form would+// execute a write. The driver splits a multi-statement request and builds the+// EXPLAIN of each statement (see pg.go and its siblings), so this validates the+// same per-statement form built the same way: a smuggled "ANALYZE DELETE FROM t"+// is not a statement the parser can plan, and an EXPLAIN ANALYZE DELETE the caller+// wrote itself is rebuilt as a plain EXPLAIN or refused before it runs.+//+// An engine whose EXPLAIN is not a statement prefix (Oracle EXPLAIN PLAN, SQL+// Server SHOWPLAN, Spanner/BigQuery plan APIs) runs its own plan API, which does+// not execute the statement, and so has nothing registered to validate here.func validateExplainStatements(instance *store.InstanceMessage, statement string, format v1pb.QueryOption_ExplainFormat) error {engine := instance.Metadata.GetEngine()+ if !parserbase.HasExplainStatement(engine) {+ return nil+ }statements, err := parserbase.SplitMultiSQL(engine, statement)if err != nil {- // No splitter for this engine: validate the whole statement wrapped once.+ // No splitter for this engine: validate the whole statement planned once.// Execution goes through the same splitter, so a request that fails to split// here fails there too rather than executing.statements = []parserbase.Statement{{Text: statement}}@@ -2050,11 +2055,11 @@ func validateExplainStatements(instance *store.InstanceMessage, statement stringif stmt.Empty {continue}- wrapped, ok := db.ExplainStatement(engine, stmt.Text, format)- if !ok {- return nil+ planned, err := parserbase.ExplainStatement(engine, stmt.Text, db.ExplainFormat(format))+ if err != nil {+ return connect.NewError(connect.CodeInvalidArgument, err)}- if err := validateQueryRequest(instance, wrapped); err != nil {+ if err := validateQueryRequest(instance, planned); err != nil {return err}}diff --git a/backend/api/v1/sql_service_test.go b/backend/api/v1/sql_service_test.goindex d0be83cc2a..a6cf627f57 100644--- a/backend/api/v1/sql_service_test.go+++ b/backend/api/v1/sql_service_test.go@@ -2,6 +2,7 @@ package v1import ("context"+ "strings""testing""connectrpc.com/connect"@@ -10,6 +11,7 @@ import ("github.com/bytebase/bytebase/backend/common"storepb "github.com/bytebase/bytebase/backend/generated-go/store"v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"+ parserbase "github.com/bytebase/bytebase/backend/plugin/parser/base""github.com/bytebase/bytebase/backend/store")@@ -376,27 +378,29 @@ func TestValidateExplainFormat(t *testing.T) {}}-// TestExplainGateRejectsSmuggledWrite locks the smuggle defense. An explain-// request carries the bare statement and the driver prefixes EXPLAIN, so-// "ANALYZE DELETE FROM t" — not valid SQL on its own — would become-// EXPLAIN ANALYZE DELETE and execute the DELETE. validateExplainStatements wraps-// each statement the way the driver does and refuses it unless read-only. Every-// prefix engine must classify the wrapped smuggle as non-read-only (by verdict or-// syntax error) so it never reaches the driver.+// explainPrefixEngines are the engines that plan a statement by prefixing EXPLAIN+// to it, and so run a different statement than the one the caller sent.//// The engine parsers are registered for the whole v1 test binary by blank imports-// elsewhere in the package, so each ValidateSQLForEditor call returns that engine's-// real verdict rather than the no-validator default.+// elsewhere in the package, so each call below returns that engine's real verdict+// rather than a no-parser default.+var explainPrefixEngines = []storepb.Engine{+ storepb.Engine_POSTGRES, storepb.Engine_MYSQL, storepb.Engine_MARIADB,+ storepb.Engine_OCEANBASE, storepb.Engine_TIDB, storepb.Engine_REDSHIFT,+ storepb.Engine_COCKROACHDB, storepb.Engine_SNOWFLAKE, storepb.Engine_CLICKHOUSE,+ storepb.Engine_STARROCKS, storepb.Engine_DORIS, storepb.Engine_HIVE,+ storepb.Engine_TRINO,+}++// TestExplainGateRejectsSmuggledWrite locks the smuggle defense. An explain+// request carries the bare statement, so "ANALYZE DELETE FROM t" — not valid SQL+// on its own — would become EXPLAIN ANALYZE DELETE and execute the DELETE if+// anything simply prefixed it. Every prefix engine must refuse it, by parsing the+// statement it was handed or by classifying the planned form as non-read-only, so+// it never reaches the driver.func TestExplainGateRejectsSmuggledWrite(t *testing.T) {t.Parallel()- engines := []storepb.Engine{- storepb.Engine_POSTGRES, storepb.Engine_MYSQL, storepb.Engine_MARIADB,- storepb.Engine_OCEANBASE, storepb.Engine_TIDB, storepb.Engine_REDSHIFT,- storepb.Engine_COCKROACHDB, storepb.Engine_SNOWFLAKE, storepb.Engine_CLICKHOUSE,- storepb.Engine_STARROCKS, storepb.Engine_DORIS, storepb.Engine_HIVE,- storepb.Engine_TRINO,- }- for _, engine := range engines {+ for _, engine := range explainPrefixEngines {t.Run(engine.String(), func(t *testing.T) {t.Parallel()instance := &store.InstanceMessage{Metadata: &storepb.Instance{Engine: engine}}@@ -406,6 +410,51 @@ func TestExplainGateRejectsSmuggledWrite(t *testing.T) {}}+// TestExplainGatePlansAPlanOnce locks the rebuild. A statement that already asks+// for a plan is planned once: the request's EXPLAIN replaces the caller's rather+// than wrapping it, which a second EXPLAIN would turn into a syntax error.+func TestExplainGatePlansAPlanOnce(t *testing.T) {+ t.Parallel()+ for _, engine := range explainPrefixEngines {+ t.Run(engine.String(), func(t *testing.T) {+ t.Parallel()+ instance := &store.InstanceMessage{Metadata: &storepb.Instance{Engine: engine}}+ require.NoError(t, validateExplainStatements(instance, "EXPLAIN SELECT 1", v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED))+ })+ }+}++// TestExplainGateNeverAnalyzes locks what the rebuild is for: an EXPLAIN ANALYZE+// of a write executes the write, so no explain request may end up running one,+// whatever the caller wrote. Each engine either plans the write without the+// caller's ANALYZE or refuses the statement — a dialect with no EXPLAIN ANALYZE+// cannot parse it, and ClickHouse and Hive have no AST to rebuild it with, so+// theirs runs as written and their read-only gate refuses it.+func TestExplainGateNeverAnalyzes(t *testing.T) {+ t.Parallel()+ for _, engine := range explainPrefixEngines {+ t.Run(engine.String(), func(t *testing.T) {+ t.Parallel()+ planned, err := parserbase.ExplainStatement(engine, "EXPLAIN ANALYZE DELETE FROM t", parserbase.ExplainFormatDefault)+ if err != nil {+ instance := &store.InstanceMessage{Metadata: &storepb.Instance{Engine: engine}}+ require.Error(t, validateExplainStatements(instance, "EXPLAIN ANALYZE DELETE FROM t", v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED),+ "a statement the parser will not plan must not reach the driver")+ return+ }+ if strings.Contains(strings.ToUpper(planned), "ANALYZE") {+ // The statement runs as the caller wrote it, so the read-only gate+ // is what stands between it and the DELETE.+ require.Equal(t, "EXPLAIN ANALYZE DELETE FROM t", planned)+ instance := &store.InstanceMessage{Metadata: &storepb.Instance{Engine: engine}}+ require.Error(t, validateExplainStatements(instance, "EXPLAIN ANALYZE DELETE FROM t", v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED))+ return+ }+ require.Equal(t, "EXPLAIN DELETE FROM t", planned)+ })+ }+}+// TestExplainGateAllowsPlans confirms the gate does not over-reject legitimate// plans. A plain EXPLAIN plans without executing, so a read or a write is allowed;// and because the driver splits a multi-statement request and prefixes EXPLAIN todiff --git a/backend/plugin/db/clickhouse/query.go b/backend/plugin/db/clickhouse/query.goindex 82ca66b50c..4cc3a8ab9c 100644--- a/backend/plugin/db/clickhouse/query.go+++ b/backend/plugin/db/clickhouse/query.go@@ -45,7 +45,11 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,for _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_CLICKHOUSE, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_CLICKHOUSE, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/cockroachdb/cockroachdb.go b/backend/plugin/db/cockroachdb/cockroachdb.goindex 8302b80f37..0ba61e6a73 100644--- a/backend/plugin/db/cockroachdb/cockroachdb.go+++ b/backend/plugin/db/cockroachdb/cockroachdb.go@@ -622,7 +622,11 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,for _, singleSQL := range singleSQLs {statement := singleSQLif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_COCKROACHDB, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_COCKROACHDB, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/explain.go b/backend/plugin/db/explain.godeleted file mode 100644index 3b96a0dc24..0000000000--- a/backend/plugin/db/explain.go+++ /dev/null@@ -1,48 +0,0 @@-package db--import (- "fmt"-- storepb "github.com/bytebase/bytebase/backend/generated-go/store"- v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"-)--// ExplainStatement returns the statement that produces a query plan for-// statement on engine, and whether engine explains by prefixing the statement-// with EXPLAIN. It is the single source of that wrapping: a driver calls it to-// build the statement it runs, and the Query handler calls it to validate the-// exact statement that will run (an EXPLAIN ANALYZE of a write is not read-only-// and is refused before execution).-//-// The second return is false for engines whose EXPLAIN is not a bare prefix and-// so does not execute the wrapped statement — Oracle (EXPLAIN PLAN FOR), SQL-// Server (SET SHOWPLAN), Spanner/BigQuery (plan APIs) — and for engines with no-// EXPLAIN at all. Those drivers produce a plan on their own and pass "" here.-func ExplainStatement(engine storepb.Engine, statement string, format v1pb.QueryOption_ExplainFormat) (string, bool) {- switch engine {- case storepb.Engine_POSTGRES:- switch format {- case v1pb.QueryOption_JSON:- return fmt.Sprintf("EXPLAIN (FORMAT JSON) %s", statement), true- case v1pb.QueryOption_XML:- return fmt.Sprintf("EXPLAIN (FORMAT XML) %s", statement), true- default:- return fmt.Sprintf("EXPLAIN %s", statement), true- }- case storepb.Engine_MYSQL,- storepb.Engine_MARIADB,- storepb.Engine_OCEANBASE,- storepb.Engine_TIDB,- storepb.Engine_REDSHIFT,- storepb.Engine_COCKROACHDB,- storepb.Engine_SNOWFLAKE,- storepb.Engine_CLICKHOUSE,- storepb.Engine_STARROCKS,- storepb.Engine_DORIS,- storepb.Engine_HIVE,- storepb.Engine_TRINO:- return fmt.Sprintf("EXPLAIN %s", statement), true- default:- return "", false- }-}diff --git a/backend/plugin/db/explain_format.go b/backend/plugin/db/explain_format.gonew file mode 100644index 0000000000..bd3982d534--- /dev/null+++ b/backend/plugin/db/explain_format.go@@ -0,0 +1,23 @@+package db++import (+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++// ExplainFormat maps the plan format a caller asked for onto the format the+// parsers take. The statement an explain request runs is built there — see+// base.ExplainStatement — and this is the only part of that which speaks the+// API's enum.+func ExplainFormat(format v1pb.QueryOption_ExplainFormat) base.ExplainFormat {+ switch format {+ case v1pb.QueryOption_TEXT:+ return base.ExplainFormatText+ case v1pb.QueryOption_JSON:+ return base.ExplainFormatJSON+ case v1pb.QueryOption_XML:+ return base.ExplainFormatXML+ default:+ return base.ExplainFormatDefault+ }+}diff --git a/backend/plugin/db/explain_format_test.go b/backend/plugin/db/explain_format_test.gonew file mode 100644index 0000000000..fb885738a8--- /dev/null+++ b/backend/plugin/db/explain_format_test.go@@ -0,0 +1,27 @@+package db++import (+ "testing"++ "github.com/stretchr/testify/require"++ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainFormat(t *testing.T) {+ tests := []struct {+ format v1pb.QueryOption_ExplainFormat+ want base.ExplainFormat+ }{+ {v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, base.ExplainFormatDefault},+ {v1pb.QueryOption_TEXT, base.ExplainFormatText},+ {v1pb.QueryOption_JSON, base.ExplainFormatJSON},+ {v1pb.QueryOption_XML, base.ExplainFormatXML},+ }+ for _, tc := range tests {+ require.Equalf(t, tc.want, ExplainFormat(tc.format), "%v", tc.format)+ }+ // A request with no option at all asks for no particular format.+ require.Equal(t, base.ExplainFormatDefault, ExplainFormat((*v1pb.QueryOption)(nil).GetExplainFormat()))+}diff --git a/backend/plugin/db/explain_test.go b/backend/plugin/db/explain_test.godeleted file mode 100644index 652c353f30..0000000000--- a/backend/plugin/db/explain_test.go+++ /dev/null@@ -1,36 +0,0 @@-package db--import (- "testing"-- "github.com/stretchr/testify/require"-- storepb "github.com/bytebase/bytebase/backend/generated-go/store"- v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"-)--func TestExplainStatement(t *testing.T) {- tests := []struct {- engine storepb.Engine- format v1pb.QueryOption_ExplainFormat- want string- wantOK bool- }{- {storepb.Engine_POSTGRES, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "EXPLAIN SELECT 1", true},- {storepb.Engine_POSTGRES, v1pb.QueryOption_JSON, "EXPLAIN (FORMAT JSON) SELECT 1", true},- {storepb.Engine_POSTGRES, v1pb.QueryOption_XML, "EXPLAIN (FORMAT XML) SELECT 1", true},- {storepb.Engine_MYSQL, v1pb.QueryOption_JSON, "EXPLAIN SELECT 1", true},- {storepb.Engine_TRINO, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "EXPLAIN SELECT 1", true},- {storepb.Engine_HIVE, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "EXPLAIN SELECT 1", true},- // Non-prefix engines (their driver builds the plan another way) report ok=false.- {storepb.Engine_ORACLE, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "", false},- {storepb.Engine_MSSQL, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "", false},- {storepb.Engine_SPANNER, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "", false},- {storepb.Engine_MONGODB, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, "", false},- }- for _, tc := range tests {- got, ok := ExplainStatement(tc.engine, "SELECT 1", tc.format)- require.Equalf(t, tc.wantOK, ok, "%s ok", tc.engine)- require.Equalf(t, tc.want, got, "%s statement", tc.engine)- }-}diff --git a/backend/plugin/db/hive/hive.go b/backend/plugin/db/hive/hive.goindex ac6157ea61..7735c1d38a 100644--- a/backend/plugin/db/hive/hive.go+++ b/backend/plugin/db/hive/hive.go@@ -192,7 +192,11 @@ func (d *Driver) QueryConn(ctx context.Context, _ *sql.Conn, statement string, qfor _, singleSQL := range singleSQLs {statement := util.TrimStatement(singleSQL.Text)if queryCtx.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_HIVE, statement, queryCtx.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_HIVE, statement, db.ExplainFormat(queryCtx.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained}result, err := d.queryStatementWithLimit(ctx, statement, queryCtx.MaximumSQLResultSize)diff --git a/backend/plugin/db/mysql/mysql.go b/backend/plugin/db/mysql/mysql.goindex 2c4b69f363..27be4889e5 100644--- a/backend/plugin/db/mysql/mysql.go+++ b/backend/plugin/db/mysql/mysql.go@@ -528,7 +528,11 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement stringfor _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_MYSQL, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_MYSQL, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/pg/pg.go b/backend/plugin/db/pg/pg.goindex 6565770986..15fba29702 100644--- a/backend/plugin/db/pg/pg.go+++ b/backend/plugin/db/pg/pg.go@@ -799,7 +799,11 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement stringfor _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_POSTGRES, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_POSTGRES, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/pg/pg_test.go b/backend/plugin/db/pg/pg_test.goindex 0eaed311be..72fe729ae1 100644--- a/backend/plugin/db/pg/pg_test.go+++ b/backend/plugin/db/pg/pg_test.go@@ -410,6 +410,22 @@ func TestQueryConnExplainFormat(t *testing.T) {require.Equal(t, "plan_target", plan[0].Plan.RelationName)require.Positive(t, plan[0].Plan.TotalCost)require.Positive(t, plan[0].Plan.PlanRows)++ // A statement that already asks for a plan is planned once: the request's+ // format replaces the caller's EXPLAIN instead of wrapping it, which the+ // server would reject as a syntax error.+ planOfPlan, err := driver.QueryConn(ctx, conn, "EXPLAIN (FORMAT TEXT) "+statement, db.QueryContext{+ Explain: true,+ Limit: 5000,+ MaximumSQLResultSize: 1 << 30,+ Option: &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON},+ })+ require.NoError(t, err)+ require.NotEmpty(t, planOfPlan)+ require.Empty(t, planOfPlan[0].GetError())+ require.NoError(t, json.Unmarshal([]byte(firstStringValue(t, planOfPlan)), &plan))+ require.Len(t, plan, 1)+ require.Equal(t, "plan_target", plan[0].Plan.RelationName)}func firstStringValue(t *testing.T, results []*v1pb.QueryResult) string {diff --git a/backend/plugin/db/redshift/redshift.go b/backend/plugin/db/redshift/redshift.goindex 085f951c45..751d4b7b47 100644--- a/backend/plugin/db/redshift/redshift.go+++ b/backend/plugin/db/redshift/redshift.go@@ -388,7 +388,11 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement stringstatement = strings.ReplaceAll(statement, fmt.Sprintf("%s.", d.databaseName), "")}if queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_REDSHIFT, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_REDSHIFT, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/snowflake/snowflake.go b/backend/plugin/db/snowflake/snowflake.goindex e492b330d6..92df80531c 100644--- a/backend/plugin/db/snowflake/snowflake.go+++ b/backend/plugin/db/snowflake/snowflake.go@@ -24,6 +24,9 @@ import ("github.com/bytebase/bytebase/backend/plugin/db/util""github.com/bytebase/bytebase/backend/plugin/parser/base"+ // Register how this engine plans a statement, for base.ExplainStatement below.+ _ "github.com/bytebase/bytebase/backend/plugin/parser/snowflake"+snow "github.com/snowflakedb/gosnowflake/v2")@@ -337,7 +340,11 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,for _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_SNOWFLAKE, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_SNOWFLAKE, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/starrocks/starrocks.go b/backend/plugin/db/starrocks/starrocks.goindex 03e2d86572..f27436ce85 100644--- a/backend/plugin/db/starrocks/starrocks.go+++ b/backend/plugin/db/starrocks/starrocks.go@@ -26,6 +26,11 @@ import ("github.com/bytebase/bytebase/backend/plugin/db""github.com/bytebase/bytebase/backend/plugin/db/util""github.com/bytebase/bytebase/backend/plugin/parser/base"++ // Register how these engines plan a statement, for base.ExplainStatement below.+ // This driver serves both.+ _ "github.com/bytebase/bytebase/backend/plugin/parser/doris"+ _ "github.com/bytebase/bytebase/backend/plugin/parser/starrocks")var (@@ -304,7 +309,11 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement stringfor _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(d.dbType, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(d.dbType, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/tidb/tidb.go b/backend/plugin/db/tidb/tidb.goindex e1e2628075..e8e381811e 100644--- a/backend/plugin/db/tidb/tidb.go+++ b/backend/plugin/db/tidb/tidb.go@@ -373,7 +373,11 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement stringfor _, singleSQL := range singleSQLs {statement := singleSQL.Textif queryContext.Explain {- statement, _ = db.ExplainStatement(storepb.Engine_TIDB, statement, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_TIDB, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ statement = explained} else if queryContext.Limit > 0 {statement = getStatementWithResultLimit(statement, queryContext.Limit)}diff --git a/backend/plugin/db/trino/trino.go b/backend/plugin/db/trino/trino.goindex 8246a29ad1..072441f1e6 100644--- a/backend/plugin/db/trino/trino.go+++ b/backend/plugin/db/trino/trino.go@@ -19,6 +19,9 @@ import ("github.com/bytebase/bytebase/backend/plugin/db""github.com/bytebase/bytebase/backend/plugin/db/util""github.com/bytebase/bytebase/backend/plugin/parser/base"++ // Register how this engine plans a statement, for base.ExplainStatement below.+ _ "github.com/bytebase/bytebase/backend/plugin/parser/trino")func init() {@@ -233,11 +236,15 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,strings.HasPrefix(upperStmt, "EXPLAIN")if queryContext.Explain {- stmt, _ = db.ExplainStatement(storepb.Engine_TRINO, stmt, queryContext.Option.GetExplainFormat())+ explained, err := base.ExplainStatement(storepb.Engine_TRINO, stmt, db.ExplainFormat(queryContext.Option.GetExplainFormat()))+ if err != nil {+ return nil, err+ }+ stmt = explainedisQuery = true- }-- if isQuery && queryContext.Limit > 0 && !strings.Contains(upperStmt, " LIMIT ") {+ } else if isQuery && queryContext.Limit > 0 && !strings.Contains(upperStmt, " LIMIT ") {+ // A plan of a statement the caller did not write answers the wrong+ // question, so the limit applies only when the statement runs.stmt = fmt.Sprintf("%s LIMIT %d", stmt, queryContext.Limit)}diff --git a/backend/plugin/parser/base/explain.go b/backend/plugin/parser/base/explain.gonew file mode 100644index 0000000000..154fc51422--- /dev/null+++ b/backend/plugin/parser/base/explain.go@@ -0,0 +1,126 @@+package base++import (+ "fmt"+ "strings"+ "sync"++ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+)++// ExplainFormat is the plan output an explain request asks for. The API's own+// format enum maps onto it where the request enters, so the parsers stay free of+// the API protos.+type ExplainFormat int++const (+ // ExplainFormatDefault is whatever plan the engine returns when the caller+ // asks for no particular format.+ ExplainFormatDefault ExplainFormat = iota+ ExplainFormatText+ ExplainFormatJSON+ ExplainFormatXML+)++// ExplainStatementFunc returns the statement that plans the single statement+// statement. See ExplainStatement for the contract every engine implements.+type ExplainStatementFunc func(statement string, format ExplainFormat) (string, error)++var (+ explainMux sync.Mutex+ explainStatements = make(map[storepb.Engine]ExplainStatementFunc)+)++// RegisterExplainStatementFunc registers how engine builds the statement that+// plans another statement. Only an engine that plans by prefixing EXPLAIN to the+// statement registers here; see ExplainStatement.+func RegisterExplainStatementFunc(engine storepb.Engine, f ExplainStatementFunc) {+ explainMux.Lock()+ defer explainMux.Unlock()+ if _, dup := explainStatements[engine]; dup {+ panic(fmt.Sprintf("Register called twice %s", engine))+ }+ explainStatements[engine] = f+}++// ExplainStatement returns the statement that produces a query plan for+// statement, which must be a single statement. It is the single source of that+// rewrite: a driver calls it to build the statement it runs, and the Query+// handler calls it to validate the exact statement that will run (an EXPLAIN+// ANALYZE of a write is not read-only and is refused before execution).+//+// The explain request owns the EXPLAIN clause. A statement that already asks for+// a plan is rebuilt around the statement it plans, so the request's format+// replaces the caller's own options and no request ever plans a plan. The one+// refusal is a caller's EXPLAIN ANALYZE: see ErrExplainAnalyzeExecutes. Where the+// engine's parser cannot say which statement is planned, the statement is+// returned unchanged rather than wrapped in a second EXPLAIN.+//+// It fails for an engine that does not plan by prefixing EXPLAIN, and so does not+// execute the statement it plans — Oracle (EXPLAIN PLAN FOR), SQL Server (SET+// SHOWPLAN), Spanner/BigQuery (plan APIs) — and for an engine with no EXPLAIN at+// all. Those drivers produce a plan on their own and never ask; a caller that+// cannot tell which kind of engine it holds asks HasExplainStatement first.+func ExplainStatement(engine storepb.Engine, statement string, format ExplainFormat) (string, error) {+ f, ok := explainStatements[engine]+ if !ok {+ return "", errors.Errorf("%s does not plan a statement by prefixing EXPLAIN", engine)+ }+ return f(statement, format)+}++// HasExplainStatement reports whether engine plans a statement by prefixing+// EXPLAIN to it, which is what makes the statement that runs something other than+// the one the caller holds.+//+// Lock-free like every other lookup here, and for the same reason: the functions+// are registered from package init functions, before any request runs.+func HasExplainStatement(engine storepb.Engine) bool {+ _, ok := explainStatements[engine]+ return ok+}++// ErrExplainAnalyzeExecutes is what an engine returns for a caller's own EXPLAIN+// ANALYZE. That statement plans by executing what it plans, which an explain+// request never does, and planning it without the ANALYZE would quietly answer a+// question the caller did not ask.+var ErrExplainAnalyzeExecutes = errors.New("EXPLAIN ANALYZE executes the statement it plans, which an explain request never does: run it as a query, or drop ANALYZE to plan the statement")++// StartsWithExplain reports whether the first keyword of statement is EXPLAIN,+// ignoring leading comments and whitespace. It stands in for an AST check on an+// engine whose parser cannot answer, which is enough to keep such an engine from+// planning a plan.+func StartsWithExplain(statement string) bool {+ s := statement+ for {+ s = strings.TrimLeft(s, " \t\r\n\v\f")+ switch {+ case strings.HasPrefix(s, "--"):+ _, rest, found := strings.Cut(s, "\n")+ if !found {+ return false+ }+ s = rest+ case strings.HasPrefix(s, "/*"):+ _, rest, found := strings.Cut(s[2:], "*/")+ if !found {+ return false+ }+ s = rest+ default:+ const explain = "EXPLAIN"+ if len(s) < len(explain) || !strings.EqualFold(s[:len(explain)], explain) {+ return false+ }+ // The keyword ends the statement or is followed by something that+ // cannot continue an identifier, so EXPLAINED is not an EXPLAIN.+ if len(s) == len(explain) {+ return true+ }+ c := s[len(explain)]+ return c != '_' && c != '$' && (c < '0' || c > '9') && (c < 'a' || c > 'z') && (c < 'A' || c > 'Z') && c < 0x80+ }+ }+}diff --git a/backend/plugin/parser/base/explain_test.go b/backend/plugin/parser/base/explain_test.gonew file mode 100644index 0000000000..48e7363ae8--- /dev/null+++ b/backend/plugin/parser/base/explain_test.go@@ -0,0 +1,33 @@+package base++import (+ "testing"++ "github.com/stretchr/testify/require"+)++func TestStartsWithExplain(t *testing.T) {+ tests := []struct {+ statement string+ want bool+ }{+ {"EXPLAIN SELECT 1", true},+ {"explain select 1", true},+ {"\n\t EXPLAIN SELECT 1", true},+ {"EXPLAIN(SELECT 1)", true},+ {"EXPLAIN", true},+ {"-- plan it\nEXPLAIN SELECT 1", true},+ {"/* plan it */EXPLAIN SELECT 1", true},+ {"/* one */ -- two\n /* three */ EXPLAIN SELECT 1", true},+ {"SELECT 1", false},+ {"EXPLAINED", false},+ {"EXPLAIN_PLAN()", false},+ {"", false},+ // A comment that never ends leaves no keyword to read.+ {"/* EXPLAIN SELECT 1", false},+ {"-- EXPLAIN SELECT 1", false},+ }+ for _, tc := range tests {+ require.Equalf(t, tc.want, StartsWithExplain(tc.statement), "%q", tc.statement)+ }+}diff --git a/backend/plugin/parser/doris/explain.go b/backend/plugin/parser/doris/explain.gonew file mode 100644index 0000000000..74a311c258--- /dev/null+++ b/backend/plugin/parser/doris/explain.go@@ -0,0 +1,64 @@+package doris++import (+ "github.com/bytebase/omni/doris/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_DORIS, explainStatement)+}++// explainStatement implements base.ExplainStatement. Doris returns one plan+// format here whatever the caller asked for: its other EXPLAIN forms are plans of+// their own shape that nothing downstream reads (supportedExplainFormats in the+// API offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*ast.ExplainStmt); ok {+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around: run what the user wrote rather than+ // plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ parsed, err := parseDorisSQL(text)+ if err != nil {+ return nil, err+ }+ if len(parsed) == 0 || parsed[0].Node() == nil {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(parsed) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ return parsed[0].Node(), nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *ast.ExplainStmt, text string) (string, bool) {+ inner := ast.NodeLoc(explain.Query)+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if inner.Start < 0 || inner.Start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[inner.Start:explain.Loc.End], true+}diff --git a/backend/plugin/parser/doris/explain_test.go b/backend/plugin/parser/doris/explain_test.gonew file mode 100644index 0000000000..87fde179e1--- /dev/null+++ b/backend/plugin/parser/doris/explain_test.go@@ -0,0 +1,41 @@+package doris++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN VERBOSE SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ {"EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}diff --git a/backend/plugin/parser/mysql/explain.go b/backend/plugin/parser/mysql/explain.gonew file mode 100644index 0000000000..4cd67ad0ee--- /dev/null+++ b/backend/plugin/parser/mysql/explain.go@@ -0,0 +1,103 @@+package mysql++import (+ "strings"++ "github.com/bytebase/omni/mysql/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_MYSQL, explainStatement)+ base.RegisterExplainStatementFunc(storepb.Engine_MARIADB, explainStatement)+ base.RegisterExplainStatementFunc(storepb.Engine_OCEANBASE, explainStatement)+}++// explainStatement implements base.ExplainStatement. MySQL returns one plan+// format here whatever the caller asked for: FORMAT=JSON and FORMAT=TREE are+// plans of their own shape that nothing downstream reads (supportedExplainFormats+// in the API offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*ast.ExplainStmt); ok {+ if explain.Analyze {+ return "", base.ErrExplainAnalyzeExecutes+ }+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around, as for EXPLAIN FOR CONNECTION or the+ // EXPLAIN tbl_name that describes a table. Run what the user wrote+ // rather than plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ list, err := ParseMySQL(text)+ if err != nil {+ return nil, convertOmniError(err, base.Statement{Text: text})+ }+ if list == nil || len(list.Items) == 0 {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(list.Items) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ return list.Items[0], nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *ast.ExplainStmt, text string) (string, bool) {+ // An executable comment moves every location after it, because the lexer+ // parses the comment's body with its markers spliced out of the text.+ if strings.Contains(text, "/*!") || strings.Contains(text, "/*M!") {+ return "", false+ }+ start, ok := explainedStart(explain.Stmt)+ if !ok {+ return "", false+ }+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if start < 0 || start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[start:explain.Loc.End], true+}++// explainedStart returns where a statement that EXPLAIN can plan begins. The+// cases are what the grammar accepts after EXPLAIN; anything else it parses there+// describes a table rather than planning a statement.+func explainedStart(node ast.Node) (int, bool) {+ switch n := node.(type) {+ case *ast.SelectStmt:+ return n.Loc.Start, true+ // REPLACE parses as an InsertStmt.+ case *ast.InsertStmt:+ return n.Loc.Start, true+ case *ast.UpdateStmt:+ return n.Loc.Start, true+ case *ast.DeleteStmt:+ return n.Loc.Start, true+ case *ast.TableStmt:+ return n.Loc.Start, true+ case *ast.ValuesStmt:+ return n.Loc.Start, true+ default:+ return 0, false+ }+}diff --git a/backend/plugin/parser/mysql/explain_test.go b/backend/plugin/parser/mysql/explain_test.gonew file mode 100644index 0000000000..af2721a054--- /dev/null+++ b/backend/plugin/parser/mysql/explain_test.go@@ -0,0 +1,65 @@+package mysql++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"DELETE FROM t", "EXPLAIN DELETE FROM t"},+ {"UPDATE t SET a = 1", "EXPLAIN UPDATE t SET a = 1"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN FORMAT=JSON SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ // An EXPLAIN with no statement to plan is left as the user wrote it: it+ // describes a table or another connection's query, and planning a plan+ // would only turn a working statement into a syntax error.+ {"EXPLAIN t", "EXPLAIN t"},+ {"DESCRIBE t", "DESCRIBE t"},+ {"EXPLAIN FOR CONNECTION 5", "EXPLAIN FOR CONNECTION 5"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with+// EXPLAIN options smuggled in front of it, which anything that simply prefixed+// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an+// EXPLAIN ANALYZE the caller wrote, which plans by executing what it plans.+func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "ANALYZE DELETE FROM t",+ "EXPLAIN ANALYZE SELECT * FROM t",+ "EXPLAIN ANALYZE DELETE FROM t",+ "FORMAT=JSON SELECT 1",+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}++// TestExplainStatementExecutableComment keeps the rebuild off text whose locations+// the lexer reports against a spliced buffer. The statement runs as written, which+// still never plans a plan.+func TestExplainStatementExecutableComment(t *testing.T) {+ const statement = "EXPLAIN /*!40001 SELECT 1 */"+ got, err := explainStatement(statement, base.ExplainFormatDefault)+ require.NoError(t, err)+ require.Equal(t, statement, got)+}diff --git a/backend/plugin/parser/pg/explain.go b/backend/plugin/parser/pg/explain.gonew file mode 100644index 0000000000..6145e53b84--- /dev/null+++ b/backend/plugin/parser/pg/explain.go@@ -0,0 +1,92 @@+package pg++import (+ "github.com/bytebase/omni/pg/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_POSTGRES, explainStatement)+ // CockroachDB parses through the PostgreSQL grammar here as it does for the+ // read-only gate (see query.go).+ base.RegisterExplainStatementFunc(storepb.Engine_COCKROACHDB, explainStatementDefaultFormat)+}++// explainStatement implements base.ExplainStatement for PostgreSQL.+func explainStatement(statement string, format base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*ast.ExplainStmt); ok {+ if isExplainAnalyzeOmni(explain) {+ return "", base.ErrExplainAnalyzeExecutes+ }+ inner, ok := explainedText(explain, statement)+ if !ok {+ // Nothing to rebuild around: run what the caller wrote rather than+ // plan a plan.+ return statement, nil+ }+ planned = inner+ }+ switch format {+ case base.ExplainFormatJSON:+ return "EXPLAIN (FORMAT JSON) " + planned, nil+ case base.ExplainFormatXML:+ return "EXPLAIN (FORMAT XML) " + planned, nil+ default:+ return "EXPLAIN " + planned, nil+ }+}++// explainStatementDefaultFormat plans in the engine's default format whatever the+// request asked for. CockroachDB's EXPLAIN takes its own option list rather than+// PostgreSQL's FORMAT, so it offers only the default plan (supportedExplainFormats+// in the API refuses any other format for it before a request gets here).+func explainStatementDefaultFormat(statement string, _ base.ExplainFormat) (string, error) {+ return explainStatement(statement, base.ExplainFormatDefault)+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ stmts, err := ParsePg(text)+ if err != nil {+ return nil, err+ }+ var node ast.Node+ for _, stmt := range stmts {+ if stmt.AST == nil {+ continue+ }+ if node != nil {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ node = stmt.AST+ }+ if node == nil {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ return node, nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *ast.ExplainStmt, text string) (string, bool) {+ // The statement runs from its WITH clause, which the location of a SELECT leaves out, to the end+ // of the EXPLAIN, which its location can also leave out, as for ORDER BY.+ start := ast.NodeLoc(explain.Query).Start+ if with := getWithClause(explain.Query); with != nil && with.Loc.Start >= 0 && with.Loc.Start < start {+ start = with.Loc.Start+ }+ if start < 0 || start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[start:explain.Loc.End], true+}diff --git a/backend/plugin/parser/pg/explain_test.go b/backend/plugin/parser/pg/explain_test.gonew file mode 100644index 0000000000..4edb402522--- /dev/null+++ b/backend/plugin/parser/pg/explain_test.go@@ -0,0 +1,89 @@+package pg++import (+ "strings"+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ format base.ExplainFormat+ want string+ }{+ {"SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},+ {"SELECT 1", base.ExplainFormatText, "EXPLAIN SELECT 1"},+ {"SELECT 1", base.ExplainFormatJSON, "EXPLAIN (FORMAT JSON) SELECT 1"},+ {"SELECT 1", base.ExplainFormatXML, "EXPLAIN (FORMAT XML) SELECT 1"},+ {"SELECT 1;", base.ExplainFormatDefault, "EXPLAIN SELECT 1;"},+ {"DELETE FROM t", base.ExplainFormatDefault, "EXPLAIN DELETE FROM t"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", base.ExplainFormatDefault, "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so the request's format replaces the user's own options and no+ // request plans a plan.+ {"EXPLAIN SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1", base.ExplainFormatJSON, "EXPLAIN (FORMAT JSON) SELECT 1"},+ {"EXPLAIN (FORMAT XML) SELECT 1", base.ExplainFormatJSON, "EXPLAIN (FORMAT JSON) SELECT 1"},+ {"EXPLAIN /* plan it */ SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},+ {"EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x", base.ExplainFormatDefault, "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ {"EXPLAIN SELECT 1 ORDER BY 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1 ORDER BY 1"},+ {"EXPLAIN (ANALYZE false) SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, tc.format)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with+// EXPLAIN options smuggled in front of it, which anything that simply prefixed+// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an+// EXPLAIN ANALYZE the caller wrote, which plans by executing what it plans.+func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "ANALYZE DELETE FROM t",+ "EXPLAIN ANALYZE SELECT 1",+ "EXPLAIN ANALYZE DELETE FROM t",+ "EXPLAIN (ANALYZE, VERBOSE) DELETE FROM t",+ "(ANALYZE) DELETE FROM t",+ "VERBOSE SELECT 1",+ "SELECT 1; SELECT 2",+ "",+ "-- nothing here",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}++// TestExplainStatementNeverPlansAPlan holds the invariant over the shapes+// PostgreSQL accepts after EXPLAIN, including those whose planned statement the+// parser may fail to locate: the statement that comes back says EXPLAIN once.+func TestExplainStatementNeverPlansAPlan(t *testing.T) {+ for _, statement := range []string{+ "EXPLAIN SELECT 1",+ "EXPLAIN INSERT INTO t VALUES (1)",+ "EXPLAIN EXECUTE p",+ "EXPLAIN DECLARE c CURSOR FOR SELECT 1",+ "EXPLAIN CREATE TABLE t AS SELECT 1",+ "EXPLAIN (COSTS OFF) VALUES (1)",+ "EXPLAIN TABLE t",+ } {+ for _, format := range []base.ExplainFormat{base.ExplainFormatDefault, base.ExplainFormatJSON} {+ got, err := explainStatement(statement, format)+ require.NoErrorf(t, err, "%q", statement)+ require.Equalf(t, 1, strings.Count(strings.ToUpper(got), "EXPLAIN"), "%q became %q", statement, got)+ }+ }+}++func TestExplainStatementCockroachDBIgnoresFormat(t *testing.T) {+ got, err := explainStatementDefaultFormat("SELECT 1", base.ExplainFormatJSON)+ require.NoError(t, err)+ require.Equal(t, "EXPLAIN SELECT 1", got)+}diff --git a/backend/plugin/parser/pg/query_type.go b/backend/plugin/parser/pg/query_type.goindex 92b1f6dfca..6908c33f69 100644--- a/backend/plugin/parser/pg/query_type.go+++ b/backend/plugin/parser/pg/query_type.go@@ -155,16 +155,11 @@ func UnwrapExplainAnalyze(node ast.Node, text string) (ast.Node, string) {if !ok || !isExplainAnalyzeOmni(explain) {return node, text}- // The statement runs from its WITH clause, which the location of a SELECT leaves out, to the end- // of the EXPLAIN, which its location can also leave out, as for ORDER BY.- start := ast.NodeLoc(explain.Query).Start- if with := getWithClause(explain.Query); with != nil && with.Loc.Start >= 0 && with.Loc.Start < start {- start = with.Loc.Start- }- if start < 0 || start >= explain.Loc.End || explain.Loc.End > len(text) {+ inner, ok := explainedText(explain, text)+ if !ok {return explain.Query, text}- return explain.Query, text[start:explain.Loc.End]+ return explain.Query, inner}// classifyExplainedQuery returns the QueryType for the query inside EXPLAINdiff --git a/backend/plugin/parser/redshift/explain.go b/backend/plugin/parser/redshift/explain.gonew file mode 100644index 0000000000..1529868671--- /dev/null+++ b/backend/plugin/parser/redshift/explain.go@@ -0,0 +1,94 @@+package redshift++import (+ redshiftast "github.com/bytebase/omni/redshift/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_REDSHIFT, explainStatement)+}++// explainStatement implements base.ExplainStatement. Redshift returns one plan+// format here whatever the caller asked for: its EXPLAIN has no machine-readable+// form (supportedExplainFormats in the API offers this engine the default plan+// only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*redshiftast.ExplainStmt); ok {+ if hasOmniExplainAnalyze(explain) {+ return "", base.ErrExplainAnalyzeExecutes+ }+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around: run what the user wrote rather than+ // plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (redshiftast.Node, error) {+ stmts, err := ParseRedshift(text)+ if err != nil {+ return nil, err+ }+ var node redshiftast.Node+ for _, stmt := range stmts {+ if stmt.AST == nil {+ continue+ }+ if node != nil {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ node = stmt.AST+ }+ if node == nil {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ return node, nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *redshiftast.ExplainStmt, text string) (string, bool) {+ // The statement runs from its WITH clause, which the location of a SELECT+ // leaves out, to the end of the EXPLAIN, which its location can also leave+ // out, as for ORDER BY.+ start := redshiftast.NodeLoc(explain.Query).Start+ if with := explainedWithClause(explain.Query); with != nil && with.Loc.Start >= 0 && with.Loc.Start < start {+ start = with.Loc.Start+ }+ if start < 0 || start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[start:explain.Loc.End], true+}++// explainedWithClause returns the WITH clause of a statement EXPLAIN can plan.+func explainedWithClause(node redshiftast.Node) *redshiftast.WithClause {+ switch n := node.(type) {+ case *redshiftast.SelectStmt:+ return n.WithClause+ case *redshiftast.InsertStmt:+ return n.WithClause+ case *redshiftast.UpdateStmt:+ return n.WithClause+ case *redshiftast.DeleteStmt:+ return n.WithClause+ default:+ return nil+ }+}diff --git a/backend/plugin/parser/redshift/explain_test.go b/backend/plugin/parser/redshift/explain_test.gonew file mode 100644index 0000000000..7a7aa5cdc1--- /dev/null+++ b/backend/plugin/parser/redshift/explain_test.go@@ -0,0 +1,49 @@+package redshift++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"DELETE FROM t", "EXPLAIN DELETE FROM t"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN VERBOSE SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with+// EXPLAIN options smuggled in front of it, which anything that simply prefixed+// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an+// EXPLAIN ANALYZE the caller wrote, which plans by executing what it plans.+func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "ANALYZE DELETE FROM t",+ "EXPLAIN ANALYZE DELETE FROM t",+ "VERBOSE SELECT 1",+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}diff --git a/backend/plugin/parser/snowflake/explain.go b/backend/plugin/parser/snowflake/explain.gonew file mode 100644index 0000000000..c9516dfb58--- /dev/null+++ b/backend/plugin/parser/snowflake/explain.go@@ -0,0 +1,73 @@+package snowflake++import (+ "github.com/bytebase/omni/snowflake/ast"+ "github.com/bytebase/omni/snowflake/parser"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_SNOWFLAKE, explainStatement)+}++// explainStatement implements base.ExplainStatement. Snowflake returns one plan+// format here whatever the caller asked for: its EXPLAIN USING JSON is a plan of+// its own shape that nothing downstream reads (supportedExplainFormats in the API+// offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*ast.ExplainStmt); ok {+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around: run what the user wrote rather than+ // plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ stmts, err := SplitSQL(text)+ if err != nil {+ return nil, err+ }+ stmts = base.FilterEmptyStatements(stmts)+ if len(stmts) == 0 {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(stmts) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ file, err := parser.Parse(stmts[0].Text)+ if err != nil {+ return nil, err+ }+ if file == nil || len(file.Stmts) == 0 {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ return file.Stmts[0], nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *ast.ExplainStmt, text string) (string, bool) {+ inner := ast.NodeLoc(explain.Stmt)+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if inner.Start < 0 || inner.Start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[inner.Start:explain.Loc.End], true+}diff --git a/backend/plugin/parser/snowflake/explain_test.go b/backend/plugin/parser/snowflake/explain_test.gonew file mode 100644index 0000000000..7f630d032a--- /dev/null+++ b/backend/plugin/parser/snowflake/explain_test.go@@ -0,0 +1,39 @@+package snowflake++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan never becomes the plan of a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN USING JSON SELECT 1", "EXPLAIN SELECT 1"},+ {" explain select 1", "EXPLAIN select 1"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}diff --git a/backend/plugin/parser/snowflake/query.go b/backend/plugin/parser/snowflake/query.goindex 1843fc760f..319432c249 100644--- a/backend/plugin/parser/snowflake/query.go+++ b/backend/plugin/parser/snowflake/query.go@@ -28,13 +28,10 @@ func init() {// Every other statement (USE, INSERT/UPDATE/DELETE/MERGE, CALL, COPY, COMMENT,// TRUNCATE, GRANT/REVOKE, CREATE/ALTER/DROP, ...) is not read-only.//-// EXPLAIN is special-cased because omni's parser does not yet support it-// (parser.Parse returns an error). The legacy listener accepted any-// other_command.explain as read-only and data-returning without inspecting the-// inner statement; we preserve that via a lexical EXPLAIN check.+// EXPLAIN is read-only and data-returning whatever it plans, without inspecting+// the inner statement, which is what the ANTLR listener before it did.func validateQuery(statement string) (bool, bool, error) {- // Split into top-level statements with the omni splitter so EXPLAIN (which- // omni cannot parse) can be classified per-segment before parsing.+ // Split first: the parser reads one statement, and the verdict is per statement.stmts, err := SplitSQL(statement)if err != nil {return false, false, errdiff --git a/backend/plugin/parser/standard/explain.go b/backend/plugin/parser/standard/explain.gonew file mode 100644index 0000000000..a08887a100--- /dev/null+++ b/backend/plugin/parser/standard/explain.go@@ -0,0 +1,24 @@+package standard++import (+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_CLICKHOUSE, explainStatement)+ base.RegisterExplainStatementFunc(storepb.Engine_HIVE, explainStatement)+}++// explainStatement implements base.ExplainStatement for the engines parsed only+// as text here. With no AST to ask which statement an EXPLAIN plans, a statement+// that already asks for a plan runs as the user wrote it; that keeps a request+// from planning a plan, which is what the rest of this package can promise.+// Both engines return one plan format whatever the caller asked for+// (supportedExplainFormats in the API offers them the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ if base.StartsWithExplain(statement) {+ return statement, nil+ }+ return "EXPLAIN " + statement, nil+}diff --git a/backend/plugin/parser/standard/explain_test.go b/backend/plugin/parser/standard/explain_test.gonew file mode 100644index 0000000000..2d55e7d878--- /dev/null+++ b/backend/plugin/parser/standard/explain_test.go@@ -0,0 +1,31 @@+package standard++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"explained_view_query()", "EXPLAIN explained_view_query()"},+ // Without an AST the user's own EXPLAIN is left as written, which is still+ // never the plan of a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"explain PIPELINE SELECT 1", "explain PIPELINE SELECT 1"},+ {"/* plan it */ EXPLAIN SELECT 1", "/* plan it */ EXPLAIN SELECT 1"},+ {"-- plan it\nEXPLAIN SELECT 1", "-- plan it\nEXPLAIN SELECT 1"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}diff --git a/backend/plugin/parser/starrocks/explain.go b/backend/plugin/parser/starrocks/explain.gonew file mode 100644index 0000000000..a089be8dfa--- /dev/null+++ b/backend/plugin/parser/starrocks/explain.go@@ -0,0 +1,64 @@+package starrocks++import (+ "github.com/bytebase/omni/starrocks/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_STARROCKS, explainStatement)+}++// explainStatement implements base.ExplainStatement. StarRocks returns one plan+// format here whatever the caller asked for: its other EXPLAIN forms are plans of+// their own shape that nothing downstream reads (supportedExplainFormats in the+// API offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*ast.ExplainStmt); ok {+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around: run what the user wrote rather than+ // plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ parsed, err := parseStarRocksSQL(text)+ if err != nil {+ return nil, err+ }+ if len(parsed) == 0 || parsed[0].Node() == nil {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(parsed) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ return parsed[0].Node(), nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *ast.ExplainStmt, text string) (string, bool) {+ inner := ast.NodeLoc(explain.Query)+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if inner.Start < 0 || inner.Start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[inner.Start:explain.Loc.End], true+}diff --git a/backend/plugin/parser/starrocks/explain_test.go b/backend/plugin/parser/starrocks/explain_test.gonew file mode 100644index 0000000000..f4df99d1d1--- /dev/null+++ b/backend/plugin/parser/starrocks/explain_test.go@@ -0,0 +1,41 @@+package starrocks++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN VERBOSE SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ {"EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}diff --git a/backend/plugin/parser/tidb/explain.go b/backend/plugin/parser/tidb/explain.gonew file mode 100644index 0000000000..88febfa3ca--- /dev/null+++ b/backend/plugin/parser/tidb/explain.go@@ -0,0 +1,101 @@+package tidb++import (+ "strings"++ omniast "github.com/bytebase/omni/tidb/ast"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_TIDB, explainStatement)+}++// explainStatement implements base.ExplainStatement. TiDB returns one plan format+// here whatever the caller asked for: its other FORMAT values are plans of their+// own shape that nothing downstream reads (supportedExplainFormats in the API+// offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*omniast.ExplainStmt); ok {+ if explain.Analyze {+ return "", base.ErrExplainAnalyzeExecutes+ }+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around, as for EXPLAIN FOR CONNECTION or the+ // EXPLAIN tbl_name that describes a table. Run what the user wrote+ // rather than plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (omniast.Node, error) {+ list, err := ParseTiDBOmni(text)+ if err != nil {+ return nil, convertOmniParseError(err, base.Statement{Text: text})+ }+ if list == nil || len(list.Items) == 0 {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(list.Items) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ return list.Items[0], nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *omniast.ExplainStmt, text string) (string, bool) {+ // An executable comment moves every location after it, because the lexer+ // parses the comment's body with its markers spliced out of the text.+ if strings.Contains(text, "/*!") || strings.Contains(text, "/*T!") {+ return "", false+ }+ start, ok := explainedStart(explain.Stmt)+ if !ok {+ return "", false+ }+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if start < 0 || start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[start:explain.Loc.End], true+}++// explainedStart returns where a statement that EXPLAIN can plan begins. The+// cases are what the grammar accepts after EXPLAIN; anything else it parses there+// describes a table rather than planning a statement.+func explainedStart(node omniast.Node) (int, bool) {+ switch n := node.(type) {+ case *omniast.SelectStmt:+ return n.Loc.Start, true+ // REPLACE parses as an InsertStmt.+ case *omniast.InsertStmt:+ return n.Loc.Start, true+ case *omniast.UpdateStmt:+ return n.Loc.Start, true+ case *omniast.DeleteStmt:+ return n.Loc.Start, true+ case *omniast.TableStmt:+ return n.Loc.Start, true+ case *omniast.ValuesStmt:+ return n.Loc.Start, true+ default:+ return 0, false+ }+}diff --git a/backend/plugin/parser/tidb/explain_test.go b/backend/plugin/parser/tidb/explain_test.gonew file mode 100644index 0000000000..da9107e15c--- /dev/null+++ b/backend/plugin/parser/tidb/explain_test.go@@ -0,0 +1,65 @@+package tidb++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"DELETE FROM t", "EXPLAIN DELETE FROM t"},+ {"UPDATE t SET a = 1", "EXPLAIN UPDATE t SET a = 1"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN FORMAT=JSON SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ // An EXPLAIN with no statement to plan is left as the user wrote it: it+ // describes a table or another connection's query, and planning a plan+ // would only turn a working statement into a syntax error.+ {"EXPLAIN t", "EXPLAIN t"},+ {"DESCRIBE t", "DESCRIBE t"},+ {"EXPLAIN FOR CONNECTION 5", "EXPLAIN FOR CONNECTION 5"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with+// EXPLAIN options smuggled in front of it, which anything that simply prefixed+// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an+// EXPLAIN ANALYZE the caller wrote, which plans by executing what it plans.+func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "ANALYZE DELETE FROM t",+ "EXPLAIN ANALYZE SELECT * FROM t",+ "EXPLAIN ANALYZE DELETE FROM t",+ "FORMAT=JSON SELECT 1",+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}++// TestExplainStatementExecutableComment keeps the rebuild off text whose locations+// the lexer reports against a spliced buffer. The statement runs as written, which+// still never plans a plan.+func TestExplainStatementExecutableComment(t *testing.T) {+ const statement = "EXPLAIN /*!40001 SELECT 1 */"+ got, err := explainStatement(statement, base.ExplainFormatDefault)+ require.NoError(t, err)+ require.Equal(t, statement, got)+}diff --git a/backend/plugin/parser/trino/explain.go b/backend/plugin/parser/trino/explain.gonew file mode 100644index 0000000000..2a3c03e139--- /dev/null+++ b/backend/plugin/parser/trino/explain.go@@ -0,0 +1,71 @@+package trino++import (+ "github.com/bytebase/omni/trino/ast"+ "github.com/bytebase/omni/trino/parser"+ "github.com/pkg/errors"++ storepb "github.com/bytebase/bytebase/backend/generated-go/store"+ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func init() {+ base.RegisterExplainStatementFunc(storepb.Engine_TRINO, explainStatement)+}++// explainStatement implements base.ExplainStatement. Trino returns one plan+// format here whatever the caller asked for: its EXPLAIN (FORMAT JSON) is a plan+// of its own shape that nothing downstream reads (supportedExplainFormats in the+// API offers this engine the default plan only).+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {+ node, err := singleStatement(statement)+ if err != nil {+ return "", err+ }+ planned := statement+ if explain, ok := node.(*parser.ExplainStmt); ok {+ if explain.Analyze {+ return "", base.ErrExplainAnalyzeExecutes+ }+ if inner, ok := explainedText(explain, statement); ok {+ planned = inner+ } else {+ // Nothing to rebuild around: run what the user wrote rather than+ // plan a plan.+ return statement, nil+ }+ }+ return "EXPLAIN " + planned, nil+}++// singleStatement returns the one statement in text. An explain request plans one+// statement at a time: both the drivers and the API gate split a multi-statement+// request first.+func singleStatement(text string) (ast.Node, error) {+ parsed, err := parseTrinoSQL(text)+ if err != nil {+ return nil, err+ }+ if len(parsed) == 0 || parsed[0].Node() == nil {+ return nil, errors.New("EXPLAIN needs a statement to plan")+ }+ if len(parsed) > 1 {+ return nil, errors.New("EXPLAIN plans a single statement")+ }+ return parsed[0].Node(), nil+}++// explainedText returns the text within text of the statement explain plans, and+// whether it could be located.+func explainedText(explain *parser.ExplainStmt, text string) (string, bool) {+ inner, ok := nodeSpan(explain.Statement)+ if !ok {+ return "", false+ }+ // The plan ends where the EXPLAIN does, which is past clauses that the+ // planned statement's own location can leave out.+ if inner.Start < 0 || inner.Start >= explain.Loc.End || explain.Loc.End > len(text) {+ return "", false+ }+ return text[inner.Start:explain.Loc.End], true+}diff --git a/backend/plugin/parser/trino/explain_test.go b/backend/plugin/parser/trino/explain_test.gonew file mode 100644index 0000000000..b314110ecc--- /dev/null+++ b/backend/plugin/parser/trino/explain_test.go@@ -0,0 +1,51 @@+package trino++import (+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/bytebase/bytebase/backend/plugin/parser/base"+)++func TestExplainStatement(t *testing.T) {+ tests := []struct {+ statement string+ want string+ }{+ {"SELECT 1", "EXPLAIN SELECT 1"},+ {"SELECT 1;", "EXPLAIN SELECT 1;"},+ {"DELETE FROM t", "EXPLAIN DELETE FROM t"},+ {"WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ // A statement that already asks for a plan is rebuilt around the statement+ // it plans, so no request plans a plan.+ {"EXPLAIN SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN (TYPE LOGICAL) SELECT 1", "EXPLAIN SELECT 1"},+ {"EXPLAIN SELECT 1 ORDER BY 1", "EXPLAIN SELECT 1 ORDER BY 1"},+ {"EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN WITH x AS (SELECT 1) SELECT * FROM x"},+ }+ for _, tc := range tests {+ got, err := explainStatement(tc.statement, base.ExplainFormatDefault)+ require.NoErrorf(t, err, "%q", tc.statement)+ require.Equalf(t, tc.want, got, "%q", tc.statement)+ }+}++// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with+// EXPLAIN options smuggled in front of it, which anything that simply prefixed+// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an+// EXPLAIN ANALYZE the caller wrote, which plans by executing what it plans.+func TestExplainStatementRejects(t *testing.T) {+ for _, statement := range []string{+ "ANALYZE DELETE FROM t",+ // An EXPLAIN ANALYZE the caller wrote plans by executing what it plans, so+ // it is refused rather than quietly planned without the ANALYZE.+ "EXPLAIN ANALYZE SELECT 1",+ "EXPLAIN ANALYZE DELETE FROM t",+ "SELECT 1; SELECT 2",+ "",+ } {+ _, err := explainStatement(statement, base.ExplainFormatDefault)+ require.Errorf(t, err, "%q", statement)+ }+}diff --git a/docs/design/query-plan-visualizer.md b/docs/design/query-plan-visualizer.mdindex 8d73f59f49..131d5f356e 100644--- a/docs/design/query-plan-visualizer.md+++ b/docs/design/query-plan-visualizer.md@@ -98,7 +98,7 @@ its name says: one refuses to execute, the other insists on it.**Both actions plan the statement Run would execute, limit included.** Thedrivers apply the result limit only when the request is not an explain-(`pg.go:801-804`, `mysql.go:530-533`), so reusing that path plans the unbounded+(`pg.go:801-809`, `mysql.go:530-538`), so reusing that path plans the unboundedquery while Run stops at the limit — and `LIMIT` changes plan shape, so the twoare different queries. The limited statement has to be carried or reconstructedbefore either action wraps it. It matters twice over for **Explain analyze**,@@ -125,7 +125,7 @@ Otherwise show the plan as text.****The backend states the format on the result; the frontend never infers it.**The server already knows: it builds explain statements through-`db.ExplainStatement` with an explicit `QueryOption.ExplainFormat`, and it+`base.ExplainStatement` with an explicit `QueryOption.ExplainFormat`, and italready parses a typed `EXPLAIN` to classify it (§2). Carrying that answer on`QueryResult` is the whole mechanism. The driver reports the format it actuallyreceived, and **unknown is a valid answer** — from MySQL 8.0.32 an omitted format@@ -165,6 +165,12 @@ statement as an explain request naming the format it wants, and the backendsubstitutes the format rather than prefixing, which is the rule §3.1 alreadysets for every statement that arrives already explaining itself.+Substitution today keeps the planned statement and nothing else: the caller's+remaining options (`VERBOSE`, `COSTS OFF`) go with the format they came with,+because the parsers locate the planned statement rather than re-render an option+list. An `EXPLAIN ANALYZE` is refused instead of being replanned, per §3.1, so+what substitution drops is never the difference between planning and executing.+**We do not silently turn a plain `EXPLAIN` into `FORMAT JSON`.** It would changewhat the user asked to see, and no SQL editor we surveyed rewrites a typed`EXPLAIN`. Supabase tried the nearest thing — parsing the text plan — and deleted@@ -332,7 +338,7 @@ plans come from **Explain analyze** (§3.1), which is a deliberate action.**It explains the statement that ran, limits included.** The driver wraps anordinary query with the result limit but skips that wrapper on the explain path-(`pg.go:801-804`), so explaining the original text would plan an unbounded query+(`pg.go:801-809`), so explaining the original text would plan an unbounded querywhen the user ran a bounded one — and PostgreSQL plans for `LIMIT`, so the twodiffer, not just in cost but in shape. The plan request and its cache carry theexecuted statement and its connection context, and View SQL shows that statement,