- EXPLAIN supported.

- Added robot test `Explain Select Repeatably Generates Messages`.

Author: general-kroll-4-life

.vscode/launch.json

@@ -185,6 +185,9 @@
         "replace /*+ AWAIT */ google.compute.firewalls set data__disabled = 'true'  where project = 'mutable-project'  and firewall = 'replacable-firewall'  returning *;",
         "select role_name from pgi.information_schema.applicable_roles order by role_name desc;",
         "SELECT * FROM datadog.organization.users;",
+        "explain select 1 as foo;",
+        "explain select name from google.compute.networks where project = 'stackql-demo';",
+        "explain select * from aws.ec2.instances where region = 'ap-southeast-2';",
       ], 
       "default": "show providers;"
     },

internal/stackql/astanalysis/earlyanalysis/first_passes.go

@@ -219,6 +219,11 @@ func (sp *standardInitialPasses) initialPasses(
 		return err
 	}
 	ast := result.AST
+	switch node := ast.(type) {
+	case *sqlparser.Explain:
+		ast = node.Statement
+	}
+
 	annotatedAST, err := annotatedast.NewAnnotatedAst(sp.parentAnnotatedAST, ast)
 	if err != nil {
 		return err
@@ -235,6 +240,8 @@ func (sp *standardInitialPasses) initialPasses(
 		switch node := subjectAST.(type) {
 		case *sqlparser.DDL:
 			subjectAST = node.SelectStatement
+			// case *sqlparser.Explain:
+			// 	subjectAST = node.Statement
 		}
 		pbi, pbiErr := planbuilderinput.NewPlanBuilderInput(
 			annotatedAST,
@@ -326,7 +333,7 @@ func (sp *standardInitialPasses) initialPasses(
 	pbi, err := planbuilderinput.NewPlanBuilderInput(
 		annotatedAST,
 		handlerCtx,
-		ast,
+		result.AST,
 		threeToFiveAgg.GetTables(),
 		threeToFiveAgg.GetAliasedColumns(),
 		threeToFiveAgg.GetAliasMap(),

internal/stackql/mcpbackend/mcp_reverse_proxy_backend_service.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"time"
 
 	"github.com/sirupsen/logrus"
 	"github.com/stackql/stackql/internal/stackql/handler"
@@ -79,6 +80,33 @@ func (b *stackqlMCPReverseProxyService) Greet(ctx context.Context, args dto.Gree
 	return "Hi " + args.Name, nil
 }
 
+func (b *stackqlMCPReverseProxyService) ExecQuery(ctx context.Context, query string) (map[string]any, error) {
+	return b.execQuery(ctx, query)
+}
+
+func (b *stackqlMCPReverseProxyService) ValidateQuery(ctx context.Context, query string) (map[string]any, error) {
+	return map[string]any{}, nil
+}
+
+func (b *stackqlMCPReverseProxyService) execQuery(ctx context.Context, query string) (map[string]any, error) {
+	r, sqlErr := b.db.Exec(query)
+	if sqlErr != nil {
+		return nil, sqlErr
+	}
+	rowsAffected, rowsAffectedErr := r.RowsAffected()
+	lastInsertId, lastInsertIdErr := r.LastInsertId()
+	rv := map[string]any{}
+	if rowsAffectedErr == nil {
+		rv["rows_affected"] = rowsAffected
+	}
+	if lastInsertIdErr == nil {
+		rv["last_insert_id"] = lastInsertId
+	}
+	oneLinerOutput := time.Now().Format("2006-01-02T15:04:05-07:00 MST")
+	rv["timestamp"] = oneLinerOutput
+	return rv, nil
+}
+
 //nolint:gocognit,funlen // acceptable
 func (b *stackqlMCPReverseProxyService) query(ctx context.Context, query string, rowLimit int) ([]map[string]any, error) {
 	r, sqlErr := b.db.Query(query)

internal/stackql/mcpbackend/mcp_service_stackql.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"time"
 
 	"github.com/sirupsen/logrus"
 	"github.com/stackql/stackql/internal/stackql/acid/tsm_physio"
@@ -319,6 +320,30 @@ func (b *stackqlMCPService) runPreprocessedQueryJSON(ctx context.Context, query
 	return results, nil
 }
 
+func (b *stackqlMCPService) ExecQuery(ctx context.Context, query string) (map[string]any, error) {
+	return b.execQuery(ctx, query)
+}
+
+func (b *stackqlMCPService) ValidateQuery(ctx context.Context, query string) (map[string]any, error) {
+	return map[string]any{}, nil
+}
+
+func (b *stackqlMCPService) execQuery(ctx context.Context, query string) (map[string]any, error) {
+	rv := map[string]any{}
+	r, ok := b.applyQuery(query)
+	if !ok {
+		return rv, fmt.Errorf("failed to extract query results")
+	}
+	messages := []string{}
+	for _, resp := range r {
+		messages = append(messages, resp.GetMessages()...)
+	}
+	rv["messages"] = messages
+	oneLinerOutput := time.Now().Format("2006-01-02T15:04:05-07:00 MST")
+	rv["timestamp"] = oneLinerOutput
+	return rv, nil
+}
+
 // func (b *stackqlMCPService) ListTableResources(ctx context.Context, hI mcp_server.HierarchyInput) ([]string, error) {
 // 	return []string{}, nil
 // }

internal/stackql/planbuilder/entrypoint.go

@@ -163,6 +163,13 @@ func (pb *standardPlanBuilder) BuildPlanFromContext(handlerCtx handler.HandlerCo
 		}
 	}
 
+	switch statement.(type) {
+	case *sqlparser.Explain:
+		// explain plans are never cacheable and always readonly
+		qPlan.SetCacheable(false)
+		qPlan.SetReadOnly(true)
+	}
+
 	if pGBuilder.getPlanGraphHolder().ContainsIndirect() {
 		qPlan.SetCacheable(false)
 	}

internal/stackql/planbuilder/plan_builder.go

@@ -112,7 +112,7 @@ func (pgb *standardPlanGraphBuilder) createInstructionFor(pbi planbuilderinput.P
 	case *sqlparser.Exec:
 		return pgb.handleExec(pbi)
 	case *sqlparser.Explain:
-		return iqlerror.GetStatementNotSupportedError("EXPLAIN")
+		return pgb.handleExplain(pbi)
 	case *sqlparser.Insert:
 		return pgb.handleInsert(pbi)
 	case *sqlparser.NativeQuery:
@@ -169,6 +169,44 @@ func (pgb *standardPlanGraphBuilder) nop(pbi planbuilderinput.PlanBuilderInput)
 	return err
 }
 
+func (pgb *standardPlanGraphBuilder) handleExplain(pbi planbuilderinput.PlanBuilderInput) error {
+	primitiveGenerator := pgb.rootPrimitiveGenerator
+	explain, _ok := pbi.GetExplain()
+	if !_ok {
+		return fmt.Errorf("could not retrieve explain AST node for statement of type '%T'", pbi.GetStatement())
+	}
+	childPbi, err := planbuilderinput.NewPlanBuilderInput(
+		pbi.GetAnnotatedAST(),
+		pbi.GetHandlerCtx(),
+		explain.Statement,
+		pbi.GetTableExprs(),
+		pbi.GetAssignedAliasedColumns(),
+		pbi.GetAliasedTables(),
+		pbi.GetColRefs(),
+		pbi.GetPlaceholderParams(),
+		pbi.GetTxnCtrlCtrs(),
+	)
+	childPbi.SetReadOnly(true)
+	if err != nil {
+		return err
+	}
+	instructionErr := pgb.createInstructionFor(childPbi)
+	explainMessages := []string{}
+	if instructionErr == nil {
+		explainMessages = append(explainMessages, "Execution plan generated successfully")
+	}
+	genErr := primitiveGenerator.AnalyzeExplain(pbi, explainMessages, instructionErr)
+	if genErr != nil {
+		return genErr
+	}
+	builder := primitiveGenerator.GetPrimitiveComposer().GetBuilder()
+	if builder == nil {
+		return fmt.Errorf("nil explain builder")
+	}
+	buildErr := builder.Build()
+	return buildErr
+}
+
 func setLogic(pbi planbuilderinput.PlanBuilderInput, setExpr *sqlparser.SetExpr) error {
 	lhsRaw := setExpr.Name.GetRawVal()
 	lhsTrimmed := strings.TrimPrefix(lhsRaw, "$.")

internal/stackql/planbuilderinput/plan_builder_input.go

@@ -15,6 +15,7 @@ import (
 
 type PlanBuilderInput interface {
 	Clone() PlanBuilderInput
+	GetChildren() []PlanBuilderInput
 	Refocus(sqlparser.SQLNode) PlanBuilderInput
 	GetAliasedTables() parserutil.TableAliasMap
 	GetAnnotatedAST() annotatedast.AnnotatedAst
@@ -46,6 +47,7 @@ type PlanBuilderInput interface {
 	GetUpdate() (*sqlparser.Update, bool)
 	GetUse() (*sqlparser.Use, bool)
 	GetSet() (*sqlparser.Set, bool)
+	GetExplain() (*sqlparser.Explain, bool)
 	IsTccSetAheadOfTime() bool
 	SetIsTccSetAheadOfTime(bool)
 	SetPrepStmtOffset(int)
@@ -61,6 +63,7 @@ type PlanBuilderInput interface {
 	IsReadOnly() bool
 	Next() (PlanBuilderInput, bool)
 	WithNext(PlanBuilderInput)
+	WithChildren([]PlanBuilderInput) PlanBuilderInput
 	SetTxnCtrlCtrs(tcc internaldto.TxnControlCounters)
 }
 
@@ -85,6 +88,7 @@ type StandardPlanBuilderInput struct {
 	isCreateMaterializedView bool
 	rawQuery                 string
 	next                     PlanBuilderInput
+	children                 []PlanBuilderInput
 }
 
 func NewPlanBuilderInput(
@@ -150,6 +154,15 @@ func (pbi *StandardPlanBuilderInput) WithNext(next PlanBuilderInput) {
 	pbi.next = next
 }
 
+func (pbi *StandardPlanBuilderInput) GetChildren() []PlanBuilderInput {
+	return pbi.children
+}
+
+func (pbi *StandardPlanBuilderInput) WithChildren(children []PlanBuilderInput) PlanBuilderInput {
+	pbi.children = children
+	return pbi
+}
+
 func (pbi *StandardPlanBuilderInput) Clone() PlanBuilderInput {
 	clonedPbi := newPlanBuilderInput(
 		pbi.annotatedAST,
@@ -390,6 +403,11 @@ func (pbi *StandardPlanBuilderInput) GetSet() (*sqlparser.Set, bool) {
 	return rv, ok
 }
 
+func (pbi *StandardPlanBuilderInput) GetExplain() (*sqlparser.Explain, bool) {
+	rv, ok := pbi.stmt.(*sqlparser.Explain)
+	return rv, ok
+}
+
 func (pbi *StandardPlanBuilderInput) GetUpdate() (*sqlparser.Update, bool) {
 	rv, ok := pbi.stmt.(*sqlparser.Update)
 	return rv, ok

internal/stackql/primitivebuilder/explain.go

@@ -0,0 +1,75 @@
+package primitivebuilder
+
+import (
+	"github.com/stackql/any-sdk/public/sqlengine"
+	"github.com/stackql/stackql/internal/stackql/handler"
+	"github.com/stackql/stackql/internal/stackql/internal_data_transfer/internaldto"
+	"github.com/stackql/stackql/internal/stackql/primitive"
+	"github.com/stackql/stackql/internal/stackql/primitivegraph"
+	"github.com/stackql/stackql/internal/stackql/util"
+)
+
+var (
+	defaultConcludeExplainMessages []string = []string{"OK"} //nolint:revive,gochecknoglobals // prefer declarative
+)
+
+type ExplainBuilder struct {
+	graph          primitivegraph.PrimitiveGraphHolder
+	handlerCtx     handler.HandlerContext
+	root           primitivegraph.PrimitiveNode
+	sqlEngine      sqlengine.SQLEngine
+	messages       []string
+	instructionErr error
+}
+
+func NewExplainBuilder(
+	graph primitivegraph.PrimitiveGraphHolder,
+	txnControlCounters internaldto.TxnControlCounters, //nolint:revive // future proofing
+	handlerCtx handler.HandlerContext,
+	sqlEngine sqlengine.SQLEngine,
+	messages []string,
+	instructionErr error,
+) Builder {
+	if len(messages) == 0 {
+		messages = []string{}
+	}
+	messages = append(messages, defaultConcludeExplainMessages...)
+	return &ExplainBuilder{
+		graph:          graph,
+		handlerCtx:     handlerCtx,
+		sqlEngine:      sqlEngine,
+		messages:       messages,
+		instructionErr: instructionErr,
+	}
+}
+
+func (nb *ExplainBuilder) Build() error {
+	pr := primitive.NewLocalPrimitive(
+		//nolint:revive // no big deal
+		func(pc primitive.IPrimitiveCtx) internaldto.ExecutorOutput {
+			if nb.instructionErr != nil {
+				return internaldto.NewErroneousExecutorOutput(nb.instructionErr)
+			}
+			return util.PrepareResultSet(
+				internaldto.NewPrepareResultSetPlusRawDTO(
+					nil,
+					nil,
+					nil,
+					nil,
+					nil,
+					internaldto.NewBackendMessages(nb.messages), nil,
+					nb.handlerCtx.GetTypingConfig()),
+			)
+		},
+	)
+	nb.root = nb.graph.CreatePrimitiveNode(pr)
+	return nil
+}
+
+func (nb *ExplainBuilder) GetRoot() primitivegraph.PrimitiveNode {
+	return nb.root
+}
+
+func (nb *ExplainBuilder) GetTail() primitivegraph.PrimitiveNode {
+	return nb.root
+}

internal/stackql/primitivegenerator/primitive_generator.go

@@ -34,6 +34,7 @@ type PrimitiveGenerator interface {
 	AddChildPrimitiveGenerator(ast sqlparser.SQLNode, leaf symtab.SymTab) PrimitiveGenerator
 	AnalyzeInsert(pbi planbuilderinput.PlanBuilderInput) error
 	AnalyzeNop(pbi planbuilderinput.PlanBuilderInput) error
+	AnalyzeExplain(pbi planbuilderinput.PlanBuilderInput, messages []string, instructionErr error) error
 	AnalyzeUpdate(pbi planbuilderinput.PlanBuilderInput) error
 	AnalyzePGInternal(pbi planbuilderinput.PlanBuilderInput) error
 	AnalyzeRegistry(pbi planbuilderinput.PlanBuilderInput) error

internal/stackql/primitivegenerator/statement_analyzer.go

@@ -68,7 +68,7 @@ func (pb *standardPrimitiveGenerator) AnalyzeStatement(
 	case *sqlparser.Exec:
 		return pb.analyzeExec(pbi)
 	case *sqlparser.Explain:
-		return iqlerror.GetStatementNotSupportedError("EXPLAIN")
+		return fmt.Errorf("direct access to %s analysis not supported", "EXPLAIN")
 	case *sqlparser.Insert:
 		return pb.AnalyzeInsert(pbi)
 	case *sqlparser.OtherRead, *sqlparser.OtherAdmin:
@@ -677,6 +677,26 @@ func (pb *standardPrimitiveGenerator) AnalyzeNop(
 	return nil
 }
 
+func (pb *standardPrimitiveGenerator) AnalyzeExplain(
+	pbi planbuilderinput.PlanBuilderInput,
+	messages []string, // future proofing free form messages
+	instructionErr error,
+) error {
+	handlerCtx := pbi.GetHandlerCtx()
+	_ = pb.PrimitiveComposer.GetGraphHolder().Blank()
+	pb.PrimitiveComposer.SetBuilder(
+		primitivebuilder.NewExplainBuilder(
+			pb.PrimitiveComposer.GetGraphHolder(),
+			pb.PrimitiveComposer.GetTxnCtrlCtrs(),
+			handlerCtx,
+			handlerCtx.GetSQLEngine(),
+			messages,
+			instructionErr,
+		),
+	)
+	return nil
+}
+
 func (pb *standardPrimitiveGenerator) analyzeExec(pbi planbuilderinput.PlanBuilderInput) error {
 	handlerCtx := pbi.GetHandlerCtx()
 	annotatedAST := pbi.GetAnnotatedAST()
@@ -871,6 +891,11 @@ func (pb *standardPrimitiveGenerator) analyzeSchemaVsMap(
 func (pb *standardPrimitiveGenerator) AnalyzePGInternal(
 	pbi planbuilderinput.PlanBuilderInput) error {
 	handlerCtx := pbi.GetHandlerCtx()
+	switch pbi.GetStatement().(type) {
+	case *sqlparser.Explain:
+		return pb.AnalyzeExplain(pbi, pbi.GetMessages(), nil)
+	}
+	// pass through
 	if backendQueryType, ok := handlerCtx.GetDBMSInternalRouter().CanRoute(pbi.GetStatement()); ok {
 		if backendQueryType == constants.BackendQuery {
 			bldr := primitivebuilder.NewRawNativeSelect(