Run several ;-separated statements at once on a single connection - temp tables, SET and scripted transactions hold. Each result set gets its own tab.
Run several ;-separated statements at once on a single connection - temp tables, SET and scripted transactions hold. Every output gets its own tab, query plans included.
Rows render as the driver yields them, in a virtualized grid that scrolls smoothly over thousands of rows. Stop long-running queries with one click.
See why a query is slow, in one tree whatever the engine. Each node's bar is its own share of the time, cost or rows, so the expensive step is the one you see first - and a row count 10x off the planner's guess is flagged where the missing index hides.
+Ctrl+Shift+E plans without running. Ctrl+Shift+A executes the statement for real rows and timings - and rolls a write back so nothing lands. Type EXPLAIN yourself and Run opens the same viewer instead of a table of raw output.
Tree view of schemas, tables and columns with instant search. Double-click a table for a SELECT, Ctrl+double-click to browse and edit its data.
{plan.raw}
+ ) : (
+ .
+export type PlanNote = 'noMetrics' | 'rolledBack' | 'tabTransaction';
+
+export interface QueryPlan {
+ driver: DriverType;
+ statement: string;
+ explainSql: string;
+ analyzed: boolean;
+ nodes: PlanNode[];
+ totalCost?: number | null;
+ planningMs?: number | null;
+ executionMs?: number | null;
+ durationMs: number;
+ notes?: string[];
+ raw: string;
+}
+
// Structured form of a failed query (see database.QueryError).
export interface QueryError {
message: string;
@@ -133,6 +176,7 @@ export interface QueryStreamRowsPayload {
}
// Finalizes one result set within a run (result carries metadata only; rows arrived via rows events).
+// A plan statement carries plan instead and streamed no rows.
export interface QueryStreamResultPayload {
seq: number;
tabId: string;
@@ -140,6 +184,7 @@ export interface QueryStreamResultPayload {
connectionId: string;
resultIndex: number;
result?: QueryResult | null;
+ plan?: QueryPlan | null;
statement?: string;
error?: string;
errorInfo?: QueryError | null;
@@ -204,13 +249,14 @@ export interface TableViewSessionState {
export type TxnState = 'idle' | 'active' | 'error';
-// One result set produced by a run: either a grid (result) or a failure (error). A run can produce
-// several - multiple statements in a script, or a stored procedure returning more than one set.
+// One output of a run: a grid, a query plan or a failure. A run can produce several, each its own tab.
export interface ResultSet {
result: QueryResult | null;
error: string | null;
errorInfo?: QueryError | null;
statement?: string;
+ /** Set for a plan statement; the set renders as the plan viewer, not a grid. */
+ plan?: QueryPlan | null;
}
export interface TabSessionState {
diff --git a/go.mod b/go.mod
index 8856ef5..cac781d 100644
--- a/go.mod
+++ b/go.mod
@@ -6,8 +6,8 @@ require (
github.com/go-sql-driver/mysql v1.10.0
github.com/google/uuid v1.6.0
github.com/jackc/pgx/v5 v5.10.0
- github.com/wailsapp/wails/v3 v3.0.0-beta.3
- golang.org/x/crypto v0.53.0
+ github.com/wailsapp/wails/v3 v3.0.0-beta.4
+ golang.org/x/crypto v0.54.0
modernc.org/sqlite v1.56.0
)
diff --git a/go.sum b/go.sum
index d606031..63a69ef 100644
--- a/go.sum
+++ b/go.sum
@@ -52,10 +52,10 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-github.com/wailsapp/wails/v3 v3.0.0-beta.3 h1:BrcZunEBVucncRx+xgkk9TzlXU4qc0ygJuEhKAAGaeA=
-github.com/wailsapp/wails/v3 v3.0.0-beta.3/go.mod h1:BzATbK71VFikMMMCo434wAi0QcaI03P+xeaWgDvQvjw=
-golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
-golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+github.com/wailsapp/wails/v3 v3.0.0-beta.4 h1:Kv5ywwZDMB0SgA1zhLM4fImf5ZsGWATTkoAQ3DS/pB8=
+github.com/wailsapp/wails/v3 v3.0.0-beta.4/go.mod h1:BzATbK71VFikMMMCo434wAi0QcaI03P+xeaWgDvQvjw=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
@@ -64,8 +64,8 @@ golang.org/x/sys v0.0.0-20200810151505-1b9f1253b3ed/go.mod h1:h1NjWce9XRLGQEsW7w
golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc=
-golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
diff --git a/internal/app/app_explain.go b/internal/app/app_explain.go
new file mode 100644
index 0000000..da02912
--- /dev/null
+++ b/internal/app/app_explain.go
@@ -0,0 +1,74 @@
+package app
+
+import (
+ "context"
+
+ "xensql/internal/database"
+)
+
+// ExplainQuery returns a normalized plan for one statement. analyze executes the statement, so a
+// write runs inside a transaction that is always rolled back; a tab with an open transaction runs
+// there instead, matching where a plain Run would have.
+func (a *App) ExplainQuery(connectionID, tabID, sql string, analyze bool) (*database.QueryPlan, error) {
+ cfg, err := a.getConnection(connectionID)
+ if err != nil {
+ return nil, err
+ }
+ stmt, err := database.SingleStatement(cfg.Driver, sql)
+ if err != nil {
+ return nil, err
+ }
+ if cfg.ReadOnly {
+ if err := database.AssertReadOnlySQLFor(cfg.Driver, stmt); err != nil {
+ return nil, err
+ }
+ }
+
+ _, queryCtx, end := a.queryContext(connectionID)
+ defer end()
+
+ conn, note, release, err := a.explainConn(queryCtx, tabID, connectionID, cfg.Driver, stmt, analyze)
+ if err != nil {
+ return nil, err
+ }
+ if release != nil {
+ defer release()
+ }
+ plan, err := database.ExplainPlan(queryCtx, conn, cfg.Driver, stmt, analyze)
+ if err != nil {
+ return nil, queryErr(err)
+ }
+ if note != "" {
+ plan.AddNote(note)
+ }
+ return plan, nil
+}
+
+// explainConn picks the connection and the note recording which: the tab's transaction, a throwaway
+// one when a measured plan would otherwise execute a write, or a plain pinned connection.
+func (a *App) explainConn(ctx context.Context, tabID, connectionID string, driver database.DriverType, stmt string, analyze bool) (database.PinnedConn, string, func(), error) {
+ if txn, ok := a.txns.Get(tabID); ok {
+ return txn, database.PlanNoteTabTransaction, nil, nil
+ }
+ s, err := a.sessionFor(connectionID)
+ if err != nil {
+ return nil, "", nil, err
+ }
+ if analyze && !database.IsReadOnlySQLFor(driver, stmt) {
+ txn, err := s.BeginTxn(ctx)
+ if err != nil {
+ return nil, "", nil, err
+ }
+ release := func() {
+ // Detached from ctx: a cancelled plan must still roll back before the conn returns to the pool.
+ _ = txn.Rollback(context.WithoutCancel(ctx))
+ txn.Close()
+ }
+ return txn, database.PlanNoteRolledBack, release, nil
+ }
+ pc, err := s.PinnedConn(ctx)
+ if err != nil {
+ return nil, "", nil, err
+ }
+ return pc, "", pc.Close, nil
+}
diff --git a/internal/app/app_explain_test.go b/internal/app/app_explain_test.go
new file mode 100644
index 0000000..a12e417
--- /dev/null
+++ b/internal/app/app_explain_test.go
@@ -0,0 +1,132 @@
+package app
+
+import (
+ "strings"
+ "testing"
+
+ "xensql/internal/database"
+)
+
+func explainTestConn(t *testing.T, readOnly bool) (*App, string) {
+ t.Helper()
+ a := appForTest(t)
+ cfg := sqliteConn(t)
+ saved, err := a.SaveConnection(cfg)
+ if err != nil {
+ t.Fatalf("save: %v", err)
+ }
+ for _, stmt := range []string{
+ "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT, age INTEGER)",
+ "CREATE INDEX users_email ON users (email)",
+ "INSERT INTO users (email, age) VALUES ('a@example.com', 30), ('b@example.com', 41)",
+ } {
+ if _, err := a.ExecuteQuery(saved.ID, stmt); err != nil {
+ t.Fatalf("setup %q: %v", stmt, err)
+ }
+ }
+ if readOnly {
+ cfg = saved
+ cfg.ReadOnly = true
+ if _, err := a.SaveConnection(cfg); err != nil {
+ t.Fatalf("mark read-only: %v", err)
+ }
+ a.Disconnect(saved.ID)
+ }
+ return a, saved.ID
+}
+
+func TestExplainQuerySQLite(t *testing.T) {
+ a, connID := explainTestConn(t, false)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM users WHERE email = 'a@example.com'", false)
+ if err != nil {
+ t.Fatalf("explain: %v", err)
+ }
+ if plan.Driver != database.DriverSQLite {
+ t.Errorf("driver = %q", plan.Driver)
+ }
+ if plan.Analyzed {
+ t.Error("plan-only run must not report itself as analyzed")
+ }
+ if plan.ExplainSQL != "EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = 'a@example.com'" {
+ t.Errorf("explain sql = %q", plan.ExplainSQL)
+ }
+ if len(plan.Nodes) == 0 {
+ t.Fatal("expected at least one plan node")
+ }
+ root := plan.Nodes[0]
+ if root.Label != "SEARCH" || root.Relation != "users" || root.Index != "users_email" {
+ t.Errorf("root = %+v, expected a SEARCH of users using users_email", root)
+ }
+ if plan.Raw == "" {
+ t.Error("expected the engine's raw output to be kept")
+ }
+}
+
+func TestExplainQuerySQLiteFullScan(t *testing.T) {
+ a, connID := explainTestConn(t, false)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM users WHERE age > 20", false)
+ if err != nil {
+ t.Fatalf("explain: %v", err)
+ }
+ if root := plan.Nodes[0]; root.Label != "SCAN" || root.Relation != "users" {
+ t.Errorf("root = %+v, expected a SCAN of users", root)
+ }
+}
+
+func TestExplainQueryAnalyzeUnsupportedOnSQLite(t *testing.T) {
+ a, connID := explainTestConn(t, false)
+
+ _, err := a.ExplainQuery(connID, "", "SELECT * FROM users", true)
+ if err == nil {
+ t.Fatal("expected an error: SQLite has no EXPLAIN ANALYZE")
+ }
+ if !strings.Contains(err.Error(), "EXPLAIN ANALYZE") {
+ t.Errorf("error should name the missing feature, got %v", err)
+ }
+}
+
+func TestExplainQueryRejectsMultipleStatements(t *testing.T) {
+ a, connID := explainTestConn(t, false)
+
+ if _, err := a.ExplainQuery(connID, "", "SELECT 1; SELECT 2", false); err == nil {
+ t.Fatal("expected an error for more than one statement")
+ }
+ if _, err := a.ExplainQuery(connID, "", " ", false); err == nil {
+ t.Fatal("expected an error for an empty statement")
+ }
+}
+
+// A read-only connection blocks planning a write, as it blocks running one.
+func TestExplainQueryReadOnlyBlocksWrites(t *testing.T) {
+ a, connID := explainTestConn(t, true)
+
+ if _, err := a.ExplainQuery(connID, "", "DELETE FROM users", false); err == nil {
+ t.Fatal("expected a read-only error")
+ }
+ if _, err := a.ExplainQuery(connID, "", "SELECT * FROM users", false); err != nil {
+ t.Fatalf("planning a read on a read-only connection should work: %v", err)
+ }
+}
+
+func TestExplainQuerySkipsHistory(t *testing.T) {
+ a, connID := explainTestConn(t, false)
+ if err := a.ClearQueryHistory(connID); err != nil {
+ t.Fatalf("clear history: %v", err)
+ }
+
+ if _, err := a.ExplainQuery(connID, "", "SELECT * FROM users", false); err != nil {
+ t.Fatalf("explain: %v", err)
+ }
+ if entries := a.GetQueryHistory(connID, 10); len(entries) != 0 {
+ t.Errorf("expected no history entries, got %v", entries)
+ }
+}
+
+func TestExplainQueryUnknownConnection(t *testing.T) {
+ a := appForTest(t)
+ if _, err := a.ExplainQuery("nope", "", "SELECT 1", false); err == nil {
+ t.Fatal("expected an error for an unknown connection")
+ }
+}
diff --git a/internal/app/app_query.go b/internal/app/app_query.go
index e3312bf..08cc100 100644
--- a/internal/app/app_query.go
+++ b/internal/app/app_query.go
@@ -52,7 +52,8 @@ type QueryStreamRowsEvent struct {
}
// QueryStreamResultEvent finalizes one result set within a run. Result carries metadata only; rows
-// were delivered via stream batches. Statement is the SQL that produced it (for labeling).
+// were delivered via stream batches. Statement is the SQL that produced it (for labeling). A plan
+// statement carries Plan instead, and delivered no rows.
type QueryStreamResultEvent struct {
Seq int `json:"seq"`
TabID string `json:"tabId"`
@@ -60,6 +61,7 @@ type QueryStreamResultEvent struct {
ConnectionID string `json:"connectionId"`
ResultIndex int `json:"resultIndex"`
Result *database.QueryResult `json:"result,omitempty"`
+ Plan *database.QueryPlan `json:"plan,omitempty"`
Statement string `json:"statement,omitempty"`
Error string `json:"error,omitempty"`
ErrorInfo *database.QueryError `json:"errorInfo,omitempty"`
@@ -120,7 +122,7 @@ func (e *streamEmitter) rows(resultIndex int, rows [][]any) {
})
}
-func (e *streamEmitter) result(resultIndex int, result *database.QueryResult, statement string, err error) {
+func (e *streamEmitter) result(resultIndex int, result *database.QueryResult, plan *database.QueryPlan, statement string, err error) {
payload := QueryStreamResultEvent{
Seq: e.nextSeq(),
TabID: e.tabID,
@@ -128,6 +130,7 @@ func (e *streamEmitter) result(resultIndex int, result *database.QueryResult, st
ConnectionID: e.connectionID,
ResultIndex: resultIndex,
Result: result,
+ Plan: plan,
Statement: statement,
}
if err != nil {
@@ -215,11 +218,11 @@ func (a *App) runBatchStream(tabID, connectionID string, statements []string) {
em.rows(idx, rows)
return nil
},
- OnResult: func(idx int, summary *database.QueryResult, statement string, err error) {
+ OnResult: func(idx int, summary *database.QueryResult, plan *database.QueryPlan, statement string, err error) {
resultCount = idx + 1
err = queryErr(err)
hist = append(hist, histEntry{statement, summary, err})
- em.result(idx, summary, statement, err)
+ em.result(idx, summary, plan, statement, err)
},
}
// Per-statement errors are reported via the result event above, so the terminal done carries
@@ -290,7 +293,7 @@ func (a *App) QueryTableStream(connectionID, tabID string, req database.TableDat
}
// A table browse is always a single result set (index 0).
result, err := s.QueryTableStream(queryCtx, req, opts)
- em.result(0, result, "", queryErr(err))
+ em.result(0, result, nil, "", queryErr(err))
em.done(1, nil)
})
return nil
diff --git a/internal/app/e2e_explain_test.go b/internal/app/e2e_explain_test.go
new file mode 100644
index 0000000..de61c2d
--- /dev/null
+++ b/internal/app/e2e_explain_test.go
@@ -0,0 +1,321 @@
+//go:build e2e
+
+package app
+
+import (
+ "fmt"
+ "regexp"
+ "strings"
+ "testing"
+
+ "xensql/internal/database"
+)
+
+// Word-bounded, so the fixture's own explain_* table name isn't mistaken for the keyword.
+var explainKeywordRe = regexp.MustCompile(`(?i)\bexplain\b`)
+
+// An indexed table with rows, so the planner has a choice to make.
+func explainFixture(t *testing.T, a *App, e engine, connID string) string {
+ t.Helper()
+ table := uniqueTable("explain")
+ createTempTable(t, a, e, connID, e.autoPKTable(table), table)
+ mustExec(t, a, connID, fmt.Sprintf("CREATE INDEX %s_name ON %s (name)",
+ strings.ReplaceAll(table, ".", "_"), qualified(e, table)))
+ for _, name := range []string{"alpha", "beta", "gamma", "delta"} {
+ mustExec(t, a, connID, fmt.Sprintf("INSERT INTO %s (name) VALUES ('%s')", qualified(e, table), name))
+ }
+ return table
+}
+
+func countNodes(nodes []database.PlanNode) int {
+ total := 0
+ for _, n := range nodes {
+ total += 1 + countNodes(n.Children)
+ }
+ return total
+}
+
+func findNode(nodes []database.PlanNode, match func(database.PlanNode) bool) (database.PlanNode, bool) {
+ for _, n := range nodes {
+ if match(n) {
+ return n, true
+ }
+ if found, ok := findNode(n.Children, match); ok {
+ return found, true
+ }
+ }
+ return database.PlanNode{}, false
+}
+
+func anyNode(nodes []database.PlanNode, match func(database.PlanNode) bool) bool {
+ _, ok := findNode(nodes, match)
+ return ok
+}
+
+func TestE2EExplainPlanOnly(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table)+" WHERE name = 'beta'", false)
+ if err != nil {
+ t.Fatalf("explain: %v", err)
+ }
+ if plan.Analyzed {
+ t.Error("a plan-only run must not report itself as analyzed")
+ }
+ if len(plan.Nodes) == 0 {
+ t.Fatal("expected at least one plan node")
+ }
+ if plan.Raw == "" {
+ t.Error("expected the engine's raw output to be kept")
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.CostTotal != nil }) {
+ t.Errorf("no node carried a cost estimate: %+v", plan.Nodes)
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.RowsPlanned != nil }) {
+ t.Errorf("no node carried a row estimate: %+v", plan.Nodes)
+ }
+ // Nothing ran.
+ if anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.RowsActual != nil || n.TimeMs != nil }) {
+ t.Error("a plan-only run reported measured values")
+ }
+ if len(plan.Notes) != 0 {
+ t.Errorf("expected no notes, got %v", plan.Notes)
+ }
+ })
+}
+
+func TestE2EExplainAnalyzeMeasures(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table), true)
+ if err != nil {
+ t.Fatalf("explain analyze: %v", err)
+ }
+ if !plan.Analyzed {
+ t.Error("expected the plan to report itself as analyzed")
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.RowsActual != nil }) {
+ t.Errorf("no node carried measured rows: %+v", plan.Nodes)
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.TimeMs != nil }) {
+ t.Errorf("no node carried a measured time: %+v", plan.Nodes)
+ }
+ // Self time drives the heat map, so it must be derivable everywhere.
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.SelfTimeMs != nil }) {
+ t.Errorf("no node carried a self time: %+v", plan.Nodes)
+ }
+ })
+}
+
+func TestE2EExplainAnalyzeRowCountsAreTotals(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table), true)
+ if err != nil {
+ t.Fatalf("explain analyze: %v", err)
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.RowsActual != nil && *n.RowsActual == 4 }) {
+ t.Errorf("expected a node reporting the 4 rows scanned: %s", planSummary(plan))
+ }
+ })
+}
+
+func TestE2EExplainIndexIsNamed(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table)+" WHERE id = 1", false)
+ if err != nil {
+ t.Fatalf("explain: %v", err)
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return n.Index != "" }) {
+ t.Errorf("expected some node to name the index it used: %s", planSummary(plan))
+ }
+ })
+}
+
+func TestE2EExplainAnalyzeRollsBackWrites(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "DELETE FROM "+qualified(e, table), true)
+ if err != nil {
+ t.Fatalf("explain analyze delete: %v", err)
+ }
+ if !planHasNote(plan, database.PlanNoteRolledBack) {
+ t.Errorf("expected the rolled-back note, got %v", plan.Notes)
+ }
+
+ result, err := a.ExecuteQuery(connID, "SELECT COUNT(*) FROM "+qualified(e, table))
+ if err != nil {
+ t.Fatalf("count: %v", err)
+ }
+ if got := countValue(t, result); got != 4 {
+ t.Fatalf("EXPLAIN ANALYZE of a DELETE left %d of 4 rows behind", got)
+ }
+ })
+}
+
+func TestE2EExplainWriteWithoutAnalyzeKeepsRows(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ if _, err := a.ExplainQuery(connID, "", "DELETE FROM "+qualified(e, table), false); err != nil {
+ t.Fatalf("explain delete: %v", err)
+ }
+ result, err := a.ExecuteQuery(connID, "SELECT COUNT(*) FROM "+qualified(e, table))
+ if err != nil {
+ t.Fatalf("count: %v", err)
+ }
+ if got := countValue(t, result); got != 4 {
+ t.Fatalf("EXPLAIN of a DELETE left %d of 4 rows behind", got)
+ }
+ })
+}
+
+func TestE2EExplainOfAnExplain(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "EXPLAIN SELECT * FROM "+qualified(e, table), false)
+ if err != nil {
+ t.Fatalf("explain of an explain: %v", err)
+ }
+ if len(plan.Nodes) == 0 {
+ t.Fatal("expected a plan for the underlying statement")
+ }
+ if got := len(explainKeywordRe.FindAllString(plan.ExplainSQL, -1)); got != 1 {
+ t.Errorf("explain sql nests %d EXPLAINs: %q", got, plan.ExplainSQL)
+ }
+ })
+}
+
+func TestE2EExplainReportsSyntaxErrors(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ if _, err := a.ExplainQuery(connID, "", "SELECT * FROM table_that_is_not_there_xensql", false); err == nil {
+ t.Fatal("expected an error for a missing table")
+ }
+ })
+}
+
+func TestE2EExplainPostgresTimings(t *testing.T) {
+ a := appForTest(t)
+ e := pgEngine()
+ connID := requireEngine(t, a, e)
+ table := explainFixture(t, a, e, connID)
+
+ plan, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table), true)
+ if err != nil {
+ t.Fatalf("explain analyze: %v", err)
+ }
+ if plan.PlanningMs == nil || *plan.PlanningMs <= 0 {
+ t.Errorf("planning time = %v", plan.PlanningMs)
+ }
+ if plan.ExecutionMs == nil || *plan.ExecutionMs <= 0 {
+ t.Errorf("execution time = %v", plan.ExecutionMs)
+ }
+ if plan.TotalCost == nil {
+ t.Error("expected a total cost")
+ }
+}
+
+func TestE2EExplainTreeHasDepth(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+ ref := qualified(e, table)
+ query := fmt.Sprintf(
+ "SELECT a.name FROM %s a JOIN %s b ON a.id = b.id JOIN %s c ON b.id = c.id ORDER BY a.name",
+ ref, ref, ref)
+
+ plan, err := a.ExplainQuery(connID, "", query, false)
+ if err != nil {
+ t.Fatalf("explain join: %v", err)
+ }
+ if got := countNodes(plan.Nodes); got < 3 {
+ t.Errorf("expected a multi-node tree for a 3-way join, got %d: %s", got, planSummary(plan))
+ }
+ if !anyNode(plan.Nodes, func(n database.PlanNode) bool { return len(n.Children) > 0 }) {
+ t.Errorf("plan tree is flat: %s", planSummary(plan))
+ }
+ })
+}
+
+func TestE2EExplainReadOnlyConnection(t *testing.T) {
+ forEachEngine(t, func(t *testing.T, a *App, e engine, connID string) {
+ table := explainFixture(t, a, e, connID)
+
+ cfg, err := a.getConnection(connID)
+ if err != nil {
+ t.Fatalf("get connection: %v", err)
+ }
+ cfg.ReadOnly = true
+ if _, err := a.SaveConnection(cfg); err != nil {
+ t.Fatalf("mark read-only: %v", err)
+ }
+ a.Disconnect(connID)
+
+ if _, err := a.ExplainQuery(connID, "", "SELECT * FROM "+qualified(e, table), false); err != nil {
+ t.Fatalf("planning a read on a read-only connection should work: %v", err)
+ }
+ if _, err := a.ExplainQuery(connID, "", "DELETE FROM "+qualified(e, table), true); err == nil {
+ t.Fatal("expected a read-only error for a measured plan of a delete")
+ }
+ })
+}
+
+func planHasNote(plan *database.QueryPlan, code string) bool {
+ for _, n := range plan.Notes {
+ if n == code {
+ return true
+ }
+ }
+ return false
+}
+
+func planSummary(plan *database.QueryPlan) string {
+ var b strings.Builder
+ fmt.Fprintf(&b, "\n%s\n", plan.ExplainSQL)
+ writePlanNodes(&b, plan.Nodes, 0)
+ return b.String()
+}
+
+func writePlanNodes(b *strings.Builder, nodes []database.PlanNode, depth int) {
+ for _, n := range nodes {
+ fmt.Fprintf(b, "%s%s relation=%q index=%q cost=%s rows=%s actual=%s time=%s\n",
+ strings.Repeat(" ", depth), n.Label, n.Relation, n.Index,
+ floatOrDash(n.CostTotal), floatOrDash(n.RowsPlanned), floatOrDash(n.RowsActual), floatOrDash(n.TimeMs))
+ writePlanNodes(b, n.Children, depth+1)
+ }
+}
+
+func floatOrDash(v *float64) string {
+ if v == nil {
+ return "-"
+ }
+ return fmt.Sprintf("%g", *v)
+}
+
+// Drivers hand a COUNT(*) back as int64, or as a string when it would lose precision in JS.
+func countValue(t *testing.T, result *database.QueryResult) int64 {
+ t.Helper()
+ if result == nil || len(result.Rows) == 0 || len(result.Rows[0]) == 0 {
+ t.Fatal("count returned no rows")
+ }
+ switch v := result.Rows[0][0].(type) {
+ case int64:
+ return v
+ case float64:
+ return int64(v)
+ case string:
+ var n int64
+ if _, err := fmt.Sscanf(v, "%d", &n); err != nil {
+ t.Fatalf("count value %q: %v", v, err)
+ }
+ return n
+ default:
+ t.Fatalf("unexpected count type %T", v)
+ return 0
+ }
+}
diff --git a/internal/app/e2e_stream_test.go b/internal/app/e2e_stream_test.go
index c6e00df..5611b23 100644
--- a/internal/app/e2e_stream_test.go
+++ b/internal/app/e2e_stream_test.go
@@ -145,7 +145,7 @@ func (c *scriptCapture) sink(batchSize int) database.ScriptSink {
c.rows[idx] = append(c.rows[idx], rows...)
return nil
},
- OnResult: func(idx int, _ *database.QueryResult, _ string, err error) {
+ OnResult: func(idx int, _ *database.QueryResult, _ *database.QueryPlan, _ string, err error) {
c.mu.Lock()
defer c.mu.Unlock()
c.results = append(c.results, scriptResult{idx, err})
diff --git a/internal/database/exec.go b/internal/database/exec.go
index 3dab596..98f43cd 100644
--- a/internal/database/exec.go
+++ b/internal/database/exec.go
@@ -69,11 +69,13 @@ func streamQueryRows(ctx context.Context, conn *sql.Conn, query string, startMs
// set fires OnMeta once, then OnBatch zero or more times; every set ends with OnResult carrying its
// summary (columns/counts/message) and any error. resultIndex is global across all statements in
// the script, so one statement that yields several result sets advances it several times.
+//
+// A statement asking for a query plan delivers no rows: its set is a single OnResult carrying plan.
type ScriptSink struct {
BatchSize int
OnMeta func(resultIndex int, columns, columnTypes []string)
OnBatch func(resultIndex int, rows [][]any) error
- OnResult func(resultIndex int, summary *QueryResult, statement string, err error)
+ OnResult func(resultIndex int, summary *QueryResult, plan *QueryPlan, statement string, err error)
}
// RunScript executes statements in order on a single connection, streaming every result set
@@ -90,6 +92,9 @@ func RunScript(ctx context.Context, conn *sql.Conn, driver DriverType, statement
}
func runScriptStatement(ctx context.Context, conn *sql.Conn, driver DriverType, stmt string, resultIndex *int, sink ScriptSink) error {
+ if req, ok := DetectPlanRequest(driver, stmt); ok {
+ return runScriptPlan(ctx, conn, driver, stmt, req, resultIndex, sink)
+ }
start := NowMs()
upper := strings.ToUpper(StripLeadingComments(stmt))
if statementReturnsRows(driver, upper) {
@@ -99,13 +104,58 @@ func runScriptStatement(ctx context.Context, conn *sql.Conn, driver DriverType,
idx := *resultIndex
*resultIndex++
if err != nil {
- sink.OnResult(idx, nil, stmt, err)
+ sink.OnResult(idx, nil, nil, stmt, err)
+ return err
+ }
+ sink.OnResult(idx, execSummary(res, start), nil, stmt, nil)
+ return nil
+}
+
+// runScriptPlan delivers a normalized plan in place of rows. Output the parsers don't recognize
+// falls back to the engine's rows rather than erroring.
+func runScriptPlan(ctx context.Context, conn *sql.Conn, driver DriverType, stmt string, req PlanRequest, resultIndex *int, sink ScriptSink) error {
+ start := NowMs()
+ idx := *resultIndex
+ *resultIndex++
+
+ res, err := bufferedQuery(ctx, conn, req.SQL)
+ if err != nil {
+ sink.OnResult(idx, nil, nil, stmt, err)
return err
}
- sink.OnResult(idx, execSummary(res, start), stmt, nil)
+ plan, parseErr := ParsePlan(driver, stmt, req.SQL, req.Analyze, res)
+ if parseErr != nil {
+ if sink.OnMeta != nil {
+ sink.OnMeta(idx, res.Columns, res.ColumnTypes)
+ }
+ if sink.OnBatch != nil && len(res.Rows) > 0 {
+ if err := sink.OnBatch(idx, res.Rows); err != nil {
+ sink.OnResult(idx, res, nil, stmt, err)
+ return err
+ }
+ }
+ sink.OnResult(idx, res, nil, stmt, nil)
+ return nil
+ }
+ plan.DurationMs = NowMs() - start
+ sink.OnResult(idx, nil, plan, stmt, nil)
return nil
}
+// Plan output is always small enough to buffer.
+func bufferedQuery(ctx context.Context, conn *sql.Conn, query string) (*QueryResult, error) {
+ var rows [][]any
+ opts := StreamOpts{OnBatch: func(batch [][]any) error {
+ rows = append(rows, batch...)
+ return nil
+ }}
+ result, err := streamQueryRows(ctx, conn, query, NowMs(), opts, &QueryResult{})
+ if result != nil {
+ result.Rows = rows
+ }
+ return result, err
+}
+
// streamResultSets runs a row-returning statement and streams each of its result sets (the first
// plus any from NextResultSet) to sink, one OnResult per set.
func streamResultSets(ctx context.Context, conn *sql.Conn, query string, start int64, resultIndex *int, sink ScriptSink) error {
@@ -113,7 +163,7 @@ func streamResultSets(ctx context.Context, conn *sql.Conn, query string, start i
if err != nil {
idx := *resultIndex
*resultIndex++
- sink.OnResult(idx, nil, query, err)
+ sink.OnResult(idx, nil, nil, query, err)
return err
}
defer rows.Close()
@@ -124,10 +174,10 @@ func streamResultSets(ctx context.Context, conn *sql.Conn, query string, start i
summary, scanErr := streamOneResultSet(ctx, rows, sink.BatchSize, idx, sink)
summary.DurationMs = NowMs() - start
if scanErr != nil {
- sink.OnResult(idx, summary, query, scanErr)
+ sink.OnResult(idx, summary, nil, query, scanErr)
return scanErr
}
- sink.OnResult(idx, summary, query, nil)
+ sink.OnResult(idx, summary, nil, query, nil)
if !rows.NextResultSet() {
break
}
@@ -164,6 +214,10 @@ func statementReturnsRows(driver DriverType, upper string) bool {
if IsSelectLike(driver, upper) || hasReturningClause(upper) {
return true
}
+ // MySQL ANALYZE always answers with rows: a status table, or MariaDB's measured plan.
+ if driver == DriverMySQL && strings.HasPrefix(upper, "ANALYZE ") {
+ return true
+ }
return strings.HasPrefix(upper, "CALL") ||
strings.HasPrefix(upper, "EXEC") ||
strings.HasPrefix(upper, "VALUES") ||
diff --git a/internal/database/explain.go b/internal/database/explain.go
new file mode 100644
index 0000000..e22fd46
--- /dev/null
+++ b/internal/database/explain.go
@@ -0,0 +1,412 @@
+package database
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "regexp"
+ "strconv"
+ "strings"
+)
+
+type PlanField struct {
+ Key string `json:"key"`
+ Value string `json:"value"`
+}
+
+// PlanNode is one operation in a normalized plan tree.
+type PlanNode struct {
+ Label string `json:"label"`
+ Detail string `json:"detail,omitempty"`
+ Relation string `json:"relation,omitempty"`
+ Index string `json:"index,omitempty"`
+ CostTotal *float64 `json:"costTotal,omitempty"`
+ CostSelf *float64 `json:"costSelf,omitempty"`
+ RowsPlanned *float64 `json:"rowsPlanned,omitempty"`
+ // Totals across every loop, not the per-loop averages Postgres and MariaDB report.
+ RowsActual *float64 `json:"rowsActual,omitempty"`
+ Loops *float64 `json:"loops,omitempty"`
+ TimeMs *float64 `json:"timeMs,omitempty"`
+ SelfTimeMs *float64 `json:"selfTimeMs,omitempty"`
+ NeverRun bool `json:"neverRun,omitempty"`
+ Fields []PlanField `json:"fields,omitempty"`
+ Children []PlanNode `json:"children,omitempty"`
+}
+
+// Note codes the frontend translates.
+const (
+ PlanNoteNoMetrics = "noMetrics"
+ PlanNoteRolledBack = "rolledBack"
+ PlanNoteTabTransaction = "tabTransaction"
+)
+
+type QueryPlan struct {
+ Driver DriverType `json:"driver"`
+ Statement string `json:"statement"`
+ ExplainSQL string `json:"explainSql"`
+ Analyzed bool `json:"analyzed"`
+ Nodes []PlanNode `json:"nodes"`
+ TotalCost *float64 `json:"totalCost,omitempty"`
+ PlanningMs *float64 `json:"planningMs,omitempty"`
+ ExecutionMs *float64 `json:"executionMs,omitempty"`
+ DurationMs int64 `json:"durationMs"`
+ Notes []string `json:"notes,omitempty"`
+ Raw string `json:"raw"`
+}
+
+func (p *QueryPlan) AddNote(code string) {
+ if p.HasNote(code) {
+ return
+ }
+ p.Notes = append(p.Notes, code)
+}
+
+func (p *QueryPlan) HasNote(code string) bool {
+ for _, existing := range p.Notes {
+ if existing == code {
+ return true
+ }
+ }
+ return false
+}
+
+// ServerVersion picks the EXPLAIN syntax: MariaDB and MySQL disagree on how to ask for a
+// measured plan, and MySQL only learned to at all in 8.0.18.
+type ServerVersion struct {
+ MariaDB bool
+ Major int
+ Minor int
+ Patch int
+}
+
+func (v ServerVersion) atLeast(major, minor, patch int) bool {
+ if v.Major != major {
+ return v.Major > major
+ }
+ if v.Minor != minor {
+ return v.Minor > minor
+ }
+ return v.Patch >= patch
+}
+
+func (v ServerVersion) String() string {
+ return fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch)
+}
+
+var (
+ versionNumberRe = regexp.MustCompile(`(\d+)\.(\d+)(?:\.(\d+))?`)
+ // Old MariaDB builds prefix "5.5.5-" so clients gating on 5.x keep working.
+ mariaCompatPrefix = "5.5.5-"
+)
+
+func ParseServerVersion(raw string) ServerVersion {
+ raw = strings.TrimSpace(raw)
+ v := ServerVersion{MariaDB: strings.Contains(strings.ToLower(raw), "mariadb")}
+ if v.MariaDB {
+ raw = strings.TrimPrefix(raw, mariaCompatPrefix)
+ }
+ m := versionNumberRe.FindStringSubmatch(raw)
+ if m == nil {
+ return v
+ }
+ v.Major, _ = strconv.Atoi(m[1])
+ v.Minor, _ = strconv.Atoi(m[2])
+ v.Patch, _ = strconv.Atoi(m[3])
+ return v
+}
+
+func SingleStatement(driver DriverType, sql string) (string, error) {
+ stmts := SplitStatements(driver, sql)
+ switch len(stmts) {
+ case 0:
+ return "", errors.New("no statement to explain")
+ case 1:
+ return stmts[0], nil
+ default:
+ return "", errors.New("select a single statement to explain")
+ }
+}
+
+var (
+ pgExplainPrefixRe = regexp.MustCompile(`(?is)^explain\s*(?:\(.*?\)\s*)?(?:analyze\s+)?(?:verbose\s+)?`)
+ mysqlExplainPrefixRe = regexp.MustCompile(`(?is)^(?:explain|analyze)\s+(?:analyze\s+)?(?:format\s*=\s*\w+\s+)?`)
+ sqliteExplainPrefixRe = regexp.MustCompile(`(?is)^explain\s+(?:query\s+plan\s+)?`)
+)
+
+// Explaining a plan query plans the underlying statement instead of nesting the EXPLAIN.
+func stripExplainPrefix(driver DriverType, stmt string) string {
+ var re *regexp.Regexp
+ switch driver {
+ case DriverPostgres:
+ re = pgExplainPrefixRe
+ case DriverMySQL:
+ re = mysqlExplainPrefixRe
+ case DriverSQLite:
+ re = sqliteExplainPrefixRe
+ default:
+ return stmt
+ }
+ prefix := re.FindString(stmt)
+ if prefix == "" {
+ return stmt
+ }
+ rest := strings.TrimSpace(stmt[len(prefix):])
+ if !explainsAStatement(strings.ToUpper(strings.TrimSpace(prefix)), rest) {
+ return stmt
+ }
+ return rest
+}
+
+func isExplainableStart(stmt string) bool {
+ switch firstKeyword(stmt) {
+ case "SELECT", "WITH", "INSERT", "UPDATE", "DELETE", "REPLACE", "MERGE", "VALUES", "TABLE":
+ return true
+ }
+ return false
+}
+
+// `ANALYZE TABLE t` is MySQL's statistics command, not a plan of a TABLE statement.
+func explainsAStatement(keyword, rest string) bool {
+ if !isExplainableStart(rest) {
+ return false
+ }
+ return !(keyword == "ANALYZE" && firstKeyword(rest) == "TABLE")
+}
+
+type PlanRequest struct {
+ SQL string
+ Analyze bool
+}
+
+type explainIntent struct {
+ analyze bool
+ format string
+ inner string
+ // SQLite's bare EXPLAIN lists bytecode instead, with nothing in common with a plan.
+ queryPlan bool
+}
+
+var (
+ pgExplainHeadRe = regexp.MustCompile(`(?is)^explain\s*(?:\(([^)]*)\)\s*)?((?:(?:analyze|verbose)\s+)*)`)
+ pgAnalyzeOptRe = regexp.MustCompile(`(?is)\banalyze\b(?:\s+(\w+))?`)
+ pgFormatOptRe = regexp.MustCompile(`(?is)\bformat\s+(\w+)`)
+ mysqlExplainHeadRe = regexp.MustCompile(`(?is)^(explain|analyze)\s+(analyze\s+)?(?:format\s*=\s*(\w+)\s+)?`)
+ sqliteExplainHeadRe = regexp.MustCompile(`(?is)^explain\s+(query\s+plan\s+)?`)
+)
+
+func isFalsey(word string) bool {
+ switch strings.ToLower(word) {
+ case "false", "off", "0":
+ return true
+ }
+ return false
+}
+
+func parseExplainIntent(driver DriverType, stmt string) (explainIntent, bool) {
+ switch driver {
+ case DriverPostgres:
+ m := pgExplainHeadRe.FindStringSubmatch(stmt)
+ if m == nil {
+ return explainIntent{}, false
+ }
+ intent := explainIntent{inner: strings.TrimSpace(stmt[len(m[0]):])}
+ if options := m[1]; options != "" {
+ if am := pgAnalyzeOptRe.FindStringSubmatch(options); am != nil {
+ intent.analyze = !isFalsey(am[1])
+ }
+ if fm := pgFormatOptRe.FindStringSubmatch(options); fm != nil {
+ intent.format = strings.ToLower(fm[1])
+ }
+ }
+ // Legacy syntax has no parentheses: EXPLAIN ANALYZE VERBOSE .
+ if strings.Contains(strings.ToLower(m[2]), "analyze") {
+ intent.analyze = true
+ }
+ return intent, true
+ case DriverMySQL:
+ m := mysqlExplainHeadRe.FindStringSubmatch(stmt)
+ if m == nil {
+ return explainIntent{}, false
+ }
+ return explainIntent{
+ analyze: strings.EqualFold(m[1], "analyze") || m[2] != "",
+ format: strings.ToLower(m[3]),
+ inner: strings.TrimSpace(stmt[len(m[0]):]),
+ }, true
+ case DriverSQLite:
+ m := sqliteExplainHeadRe.FindStringSubmatch(stmt)
+ if m == nil {
+ return explainIntent{}, false
+ }
+ return explainIntent{inner: strings.TrimSpace(stmt[len(m[0]):]), queryPlan: m[1] != ""}, true
+ default:
+ return explainIntent{}, false
+ }
+}
+
+// DetectPlanRequest reports whether a typed statement asks for a plan, and which EXPLAIN to run.
+// Output that already carries structure (any FORMAT JSON, MySQL's EXPLAIN ANALYZE tree, SQLite's
+// EXPLAIN QUERY PLAN) runs as typed; Postgres text and MySQL's traditional table are asked again
+// in JSON. ok is false where the user wants raw output: a named text/XML/YAML/traditional format,
+// or SQLite's bytecode EXPLAIN.
+func DetectPlanRequest(driver DriverType, stmt string) (PlanRequest, bool) {
+ stmt = strings.TrimSpace(StripLeadingComments(stmt))
+ first := firstKeyword(stmt)
+ if first != "EXPLAIN" && !(driver == DriverMySQL && first == "ANALYZE") {
+ return PlanRequest{}, false
+ }
+ intent, ok := parseExplainIntent(driver, stmt)
+ if !ok || !explainsAStatement(first, intent.inner) {
+ return PlanRequest{}, false
+ }
+
+ switch driver {
+ case DriverPostgres:
+ switch intent.format {
+ case "json":
+ return PlanRequest{SQL: stmt, Analyze: intent.analyze}, true
+ case "":
+ sql, err := BuildExplainSQL(driver, ServerVersion{}, intent.inner, intent.analyze)
+ if err != nil {
+ return PlanRequest{}, false
+ }
+ return PlanRequest{SQL: sql, Analyze: intent.analyze}, true
+ default:
+ return PlanRequest{}, false
+ }
+ case DriverMySQL:
+ switch intent.format {
+ case "json", "tree":
+ return PlanRequest{SQL: stmt, Analyze: intent.analyze}, true
+ case "":
+ // EXPLAIN ANALYZE already answers with the tree; other bare forms are the traditional table.
+ if intent.analyze && first == "EXPLAIN" {
+ return PlanRequest{SQL: stmt, Analyze: true}, true
+ }
+ if intent.analyze {
+ return PlanRequest{SQL: "ANALYZE FORMAT=JSON " + intent.inner, Analyze: true}, true
+ }
+ return PlanRequest{SQL: "EXPLAIN FORMAT=JSON " + intent.inner, Analyze: false}, true
+ default:
+ return PlanRequest{}, false
+ }
+ case DriverSQLite:
+ if !intent.queryPlan {
+ return PlanRequest{}, false
+ }
+ return PlanRequest{SQL: stmt, Analyze: false}, true
+ default:
+ return PlanRequest{}, false
+ }
+}
+
+// BuildExplainSQL renders the EXPLAIN for driver. analyze means the statement actually runs, so
+// callers must isolate a write themselves.
+func BuildExplainSQL(driver DriverType, sv ServerVersion, stmt string, analyze bool) (string, error) {
+ stmt = strings.TrimSpace(strings.TrimSuffix(strings.TrimSpace(stmt), ";"))
+ if stmt == "" {
+ return "", errors.New("no statement to explain")
+ }
+ stmt = stripExplainPrefix(driver, stmt)
+ switch driver {
+ case DriverPostgres:
+ if analyze {
+ return "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + stmt, nil
+ }
+ return "EXPLAIN (FORMAT JSON) " + stmt, nil
+ case DriverMySQL:
+ switch {
+ case !analyze:
+ return "EXPLAIN FORMAT=JSON " + stmt, nil
+ case sv.MariaDB:
+ return "ANALYZE FORMAT=JSON " + stmt, nil
+ case sv.atLeast(8, 0, 18):
+ // MySQL only accepts FORMAT=JSON on EXPLAIN ANALYZE from 8.3; TREE works from 8.0.18.
+ return "EXPLAIN ANALYZE " + stmt, nil
+ default:
+ return "", fmt.Errorf("EXPLAIN ANALYZE needs MySQL 8.0.18 or newer (server reports %s)", sv)
+ }
+ case DriverSQLite:
+ if analyze {
+ return "", errors.New("SQLite has no EXPLAIN ANALYZE; explain without it for the plan shape")
+ }
+ return "EXPLAIN QUERY PLAN " + stmt, nil
+ default:
+ return "", fmt.Errorf("unsupported driver: %s", driver)
+ }
+}
+
+// ExplainPlan runs the driver's EXPLAIN for stmt on conn and normalizes the output. conn is pinned
+// so an ANALYZE the caller wrapped in a transaction stays inside it.
+func ExplainPlan(ctx context.Context, conn PinnedConn, driver DriverType, stmt string, analyze bool) (*QueryPlan, error) {
+ var sv ServerVersion
+ if driver == DriverMySQL && analyze {
+ detected, err := detectServerVersion(ctx, conn)
+ if err != nil {
+ return nil, err
+ }
+ sv = detected
+ }
+ explainSQL, err := BuildExplainSQL(driver, sv, stmt, analyze)
+ if err != nil {
+ return nil, err
+ }
+ start := NowMs()
+ res, err := runBufferedOn(ctx, conn, explainSQL)
+ if err != nil {
+ return nil, err
+ }
+ plan, err := ParsePlan(driver, stmt, explainSQL, analyze, res)
+ if err != nil {
+ return nil, err
+ }
+ plan.DurationMs = NowMs() - start
+ return plan, nil
+}
+
+func runBufferedOn(ctx context.Context, conn PinnedConn, sql string) (*QueryResult, error) {
+ return collectStream(func(opts StreamOpts) (*QueryResult, error) {
+ return conn.ExecuteStream(ctx, sql, opts)
+ })
+}
+
+func detectServerVersion(ctx context.Context, conn PinnedConn) (ServerVersion, error) {
+ res, err := runBufferedOn(ctx, conn, "SELECT VERSION()")
+ if err != nil {
+ return ServerVersion{}, err
+ }
+ return ParseServerVersion(planString(firstCell(res))), nil
+}
+
+func ParsePlan(driver DriverType, stmt, explainSQL string, analyze bool, res *QueryResult) (*QueryPlan, error) {
+ if res == nil || len(res.Rows) == 0 {
+ return nil, errors.New("the server returned no plan")
+ }
+ plan := &QueryPlan{
+ Driver: driver,
+ Statement: stmt,
+ ExplainSQL: explainSQL,
+ Analyzed: analyze,
+ // One text column for both JSON formats and the tree text; parseSQLitePlan re-renders its own.
+ Raw: joinFirstColumn(res),
+ }
+ var err error
+ switch driver {
+ case DriverPostgres:
+ err = parsePostgresPlan(plan)
+ case DriverMySQL:
+ err = parseMySQLPlan(plan)
+ case DriverSQLite:
+ parseSQLitePlan(plan, res)
+ default:
+ err = fmt.Errorf("unsupported driver: %s", driver)
+ }
+ if err != nil {
+ return nil, err
+ }
+ if len(plan.Nodes) == 0 {
+ return nil, errors.New("the server returned no plan")
+ }
+ // Notes carry only what the viewer can't show otherwise; the badge already reports estimates.
+ return plan, nil
+}
diff --git a/internal/database/explain_parse.go b/internal/database/explain_parse.go
new file mode 100644
index 0000000..08b0616
--- /dev/null
+++ b/internal/database/explain_parse.go
@@ -0,0 +1,701 @@
+package database
+
+import (
+ "encoding/json"
+ "fmt"
+ "regexp"
+ "strconv"
+ "strings"
+)
+
+// planBuilder builds a tree whose shape is only known while scanning (MySQL indented text,
+// SQLite's id/parent rows). finish() flattens bottom-up, so a node is finalized after its children.
+type planBuilder struct {
+ node PlanNode
+ children []*planBuilder
+}
+
+func (b *planBuilder) finish() PlanNode {
+ for _, child := range b.children {
+ b.node.Children = append(b.node.Children, child.finish())
+ }
+ finalizeNode(&b.node)
+ return b.node
+}
+
+func finishAll(builders []*planBuilder) []PlanNode {
+ nodes := make([]PlanNode, 0, len(builders))
+ for _, b := range builders {
+ nodes = append(nodes, b.finish())
+ }
+ return nodes
+}
+
+// finalizeNode derives whichever of the inclusive/exclusive metrics the engine left out. Clamped at
+// zero: Postgres leaves InitPlan/SubPlan children out of a parent's total.
+func finalizeNode(n *PlanNode) {
+ var childCost, childTime float64
+ var haveChildCost, haveChildTime bool
+ for i := range n.Children {
+ if c := n.Children[i].CostTotal; c != nil {
+ childCost += *c
+ haveChildCost = true
+ }
+ if t := n.Children[i].TimeMs; t != nil {
+ childTime += *t
+ haveChildTime = true
+ }
+ }
+ n.CostTotal, n.CostSelf = deriveTotals(n.CostTotal, n.CostSelf, childCost, haveChildCost)
+ n.TimeMs, n.SelfTimeMs = deriveTotals(n.TimeMs, n.SelfTimeMs, childTime, haveChildTime)
+}
+
+// Postgres reports the inclusive value, MariaDB an exclusive one, and either can be missing.
+func deriveTotals(total, self *float64, childSum float64, haveChildren bool) (*float64, *float64) {
+ switch {
+ case total != nil && self == nil:
+ return total, ptrFloat(max(0, *total-childSum))
+ case total == nil && self != nil:
+ return ptrFloat(*self + childSum), self
+ case total == nil && self == nil && haveChildren:
+ return ptrFloat(childSum), ptrFloat(0)
+ default:
+ return total, self
+ }
+}
+
+// ---------- Postgres: EXPLAIN (FORMAT JSON) ----------
+
+// Already first-class metrics.
+var pgFirstClassKeys = map[string]bool{
+ "Node Type": true, "Plans": true, "Relation Name": true, "Alias": true, "Index Name": true,
+ "Total Cost": true, "Plan Rows": true, "Join Type": true, "Strategy": true,
+ "Subplan Name": true, "Parallel Aware": true,
+ "Actual Total Time": true, "Actual Rows": true, "Actual Loops": true,
+}
+
+// Most specific clause first.
+var pgDetailKeys = []string{
+ "Index Cond", "Recheck Cond", "TID Cond", "Hash Cond", "Merge Cond", "Join Filter",
+ "Filter", "One-Time Filter", "Sort Key", "Group Key", "Presorted Key", "Cache Key",
+ "Function Call", "Table Function Name", "CTE Name", "Conflict Filter",
+}
+
+func parsePostgresPlan(plan *QueryPlan) error {
+ var envelopes []map[string]any
+ if err := json.Unmarshal([]byte(plan.Raw), &envelopes); err != nil {
+ return fmt.Errorf("could not read the Postgres plan: %w", err)
+ }
+ for _, env := range envelopes {
+ root, ok := env["Plan"].(map[string]any)
+ if !ok {
+ continue
+ }
+ plan.Nodes = append(plan.Nodes, pgNode(root))
+ if v := optFloat(env["Planning Time"]); v != nil {
+ plan.PlanningMs = v
+ }
+ if v := optFloat(env["Execution Time"]); v != nil {
+ plan.ExecutionMs = v
+ }
+ }
+ if len(plan.Nodes) > 0 {
+ plan.TotalCost = plan.Nodes[0].CostTotal
+ }
+ return nil
+}
+
+func pgNode(raw map[string]any) PlanNode {
+ detailKey, detail := pgDetail(raw)
+ n := PlanNode{
+ Label: pgLabel(raw),
+ Detail: detail,
+ Relation: pgRelation(raw),
+ Index: planString(raw["Index Name"]),
+ CostTotal: optFloat(raw["Total Cost"]),
+ RowsPlanned: optFloat(raw["Plan Rows"]),
+ Fields: planFields(raw, pgFirstClassKeys, detailKey),
+ }
+ // Postgres reports per-loop averages; scale by loops so nested-loop nodes compare fairly.
+ loops := 1.0
+ if v, ok := planFloat(raw["Actual Loops"]); ok {
+ n.Loops = ptrFloat(v)
+ n.NeverRun = v == 0
+ loops = v
+ }
+ if v, ok := planFloat(raw["Actual Total Time"]); ok {
+ n.TimeMs = ptrFloat(v * loops)
+ }
+ if v, ok := planFloat(raw["Actual Rows"]); ok {
+ n.RowsActual = ptrFloat(v * loops)
+ }
+ for _, child := range asObjectSlice(raw["Plans"]) {
+ n.Children = append(n.Children, pgNode(child))
+ }
+ finalizeNode(&n)
+ return n
+}
+
+func pgLabel(raw map[string]any) string {
+ label := planString(raw["Node Type"])
+ if label == "" {
+ label = "Node"
+ }
+ if join := planString(raw["Join Type"]); join != "" && join != "Inner" {
+ label += " (" + join + ")"
+ }
+ if strategy := planString(raw["Strategy"]); strategy != "" && strategy != "Plain" {
+ label += " (" + strategy + ")"
+ }
+ if raw["Parallel Aware"] == true {
+ label = "Parallel " + label
+ }
+ if name := planString(raw["Subplan Name"]); name != "" {
+ label = name + ": " + label
+ }
+ return label
+}
+
+func pgRelation(raw map[string]any) string {
+ relation := planString(raw["Relation Name"])
+ alias := planString(raw["Alias"])
+ if alias == "" || alias == relation {
+ return relation
+ }
+ if relation == "" {
+ return alias
+ }
+ return relation + " " + alias
+}
+
+// pgDetail returns the clause and its key, so planFields can skip what's already displayed.
+func pgDetail(raw map[string]any) (string, string) {
+ for _, key := range pgDetailKeys {
+ if v := planString(raw[key]); v != "" {
+ return key, v
+ }
+ }
+ return "", ""
+}
+
+// ---------- MySQL / MariaDB ----------
+
+func parseMySQLPlan(plan *QueryPlan) error {
+ if strings.HasPrefix(strings.TrimSpace(plan.Raw), "{") {
+ return parseMySQLJSONPlan(plan)
+ }
+ parseMySQLTreePlan(plan)
+ return nil
+}
+
+// Operation keys MySQL and MariaDB use; anything unlisted falls back to the humanized key.
+var mysqlOpLabels = map[string]string{
+ "query_block": "Query block",
+ "table": "Table",
+ "nested_loop": "Nested loop",
+ "ordering_operation": "Ordering",
+ "grouping_operation": "Grouping",
+ "duplicates_removal": "Duplicates removal",
+ "materialized_from_subquery": "Materialized subquery",
+ "union_result": "Union result",
+ "query_specifications": "Query specification",
+ "buffer_result": "Buffer result",
+ "block-nl-join": "Block nested loop join",
+ "read_sorted_file": "Read sorted file",
+ "temporary_table": "Temporary table",
+ "attached_subqueries": "Attached subquery",
+ "select_list_subqueries": "Select list subquery",
+ "having_subqueries": "Having subquery",
+ "optimized_away_subqueries": "Optimized-away subquery",
+ "update_value_subqueries": "Update value subquery",
+ "subqueries": "Subquery",
+ "insert_from": "Insert from",
+}
+
+// Folded into the parent instead of becoming a child node.
+var mysqlFoldedObjects = map[string]bool{"cost_info": true}
+
+var mysqlFirstClassKeys = map[string]bool{
+ "table_name": true, "access_type": true, "key": true, "cost_info": true, "cost": true,
+ "rows_produced_per_join": true, "rows": true,
+ "r_rows": true, "r_loops": true, "r_total_time_ms": true,
+ "r_table_time_ms": true, "r_other_time_ms": true,
+}
+
+// Most specific clause first.
+var mysqlDetailKeys = []string{"attached_condition", "index_condition"}
+
+func parseMySQLJSONPlan(plan *QueryPlan) error {
+ var root map[string]any
+ if err := json.Unmarshal([]byte(plan.Raw), &root); err != nil {
+ return fmt.Errorf("could not read the MySQL plan: %w", err)
+ }
+ for _, key := range sortedKeys(root) {
+ obj, ok := root[key].(map[string]any)
+ if !ok {
+ continue
+ }
+ plan.Nodes = append(plan.Nodes, mysqlNode(key, obj))
+ }
+ if len(plan.Nodes) > 0 {
+ plan.TotalCost = plan.Nodes[0].CostTotal
+ plan.ExecutionMs = plan.Nodes[0].TimeMs
+ }
+ return nil
+}
+
+func mysqlNode(key string, raw map[string]any) PlanNode {
+ detailKey, detail := firstStringField(raw, mysqlDetailKeys)
+ n := PlanNode{
+ Label: mysqlLabel(key, raw),
+ Detail: detail,
+ Relation: planString(raw["table_name"]),
+ Index: planString(raw["key"]),
+ Fields: planFields(raw, mysqlFirstClassKeys, detailKey),
+ }
+ mysqlCost(&n, raw)
+ mysqlRowsAndTime(&n, raw)
+ n.Children = mysqlChildren(raw)
+ finalizeNode(&n)
+ return n
+}
+
+// MySQL nests cost under cost_info, MariaDB 11 reports a flat per-node cost. prefix_cost is the
+// running cost of the join prefix, so summing it double-counts; read+eval is the node's own.
+func mysqlCost(n *PlanNode, raw map[string]any) {
+ info, _ := raw["cost_info"].(map[string]any)
+ n.Fields = append(n.Fields, planFields(info, nil, "")...)
+ if flat := optFloat(raw["cost"]); flat != nil {
+ n.CostSelf = flat
+ return
+ }
+ if info == nil {
+ return
+ }
+ n.CostTotal = optFloat(info["query_cost"])
+ read, hasRead := planFloat(info["read_cost"])
+ eval, hasEval := planFloat(info["eval_cost"])
+ if hasRead || hasEval {
+ n.CostSelf = ptrFloat(read + eval)
+ }
+}
+
+func mysqlRowsAndTime(n *PlanNode, raw map[string]any) {
+ n.RowsPlanned = firstFloat(raw["rows_produced_per_join"], raw["rows_examined_per_scan"], raw["rows"])
+ // MariaDB's r_rows is per-loop like Postgres; its time counters are already totals.
+ loops := 1.0
+ if v, ok := planFloat(raw["r_loops"]); ok {
+ n.Loops = ptrFloat(v)
+ n.NeverRun = v == 0
+ loops = v
+ }
+ if v, ok := planFloat(raw["r_rows"]); ok {
+ n.RowsActual = ptrFloat(v * loops)
+ }
+ if v := optFloat(raw["r_total_time_ms"]); v != nil {
+ n.TimeMs = v
+ return
+ }
+ table, hasTable := planFloat(raw["r_table_time_ms"])
+ other, hasOther := planFloat(raw["r_other_time_ms"])
+ if hasTable || hasOther {
+ n.SelfTimeMs = ptrFloat(table + other)
+ }
+}
+
+func mysqlLabel(key string, raw map[string]any) string {
+ label := mysqlOpLabels[key]
+ if label == "" {
+ label = humanizeKey(key)
+ }
+ if access := planString(raw["access_type"]); access != "" {
+ label += " (" + access + ")"
+ }
+ if key == "query_block" {
+ if id := planString(raw["select_id"]); id != "" {
+ label += " #" + id
+ }
+ }
+ return label
+}
+
+// Every nested object is a child; an array of objects becomes one grouping node holding them.
+func mysqlChildren(raw map[string]any) []PlanNode {
+ var children []PlanNode
+ for _, key := range sortedKeys(raw) {
+ if mysqlFoldedObjects[key] {
+ continue
+ }
+ switch v := raw[key].(type) {
+ case map[string]any:
+ children = append(children, mysqlNode(key, v))
+ case []any:
+ if group, ok := mysqlGroupNode(key, v); ok {
+ children = append(children, group)
+ }
+ }
+ }
+ return children
+}
+
+// ok=false for arrays of scalars (possible_keys, used_columns), which planFields renders instead.
+func mysqlGroupNode(key string, arr []any) (PlanNode, bool) {
+ objects := asObjectSlice(arr)
+ if len(objects) == 0 || len(objects) != len(arr) {
+ return PlanNode{}, false
+ }
+ group := PlanNode{Label: firstNonEmpty(mysqlOpLabels[key], humanizeKey(key))}
+ for _, obj := range objects {
+ // Unwrap the single-key envelopes MySQL uses so the child is labelled by its operation.
+ if innerKey, inner, ok := soleObjectEntry(obj); ok {
+ group.Children = append(group.Children, mysqlNode(innerKey, inner))
+ continue
+ }
+ group.Children = append(group.Children, mysqlNode(key, obj))
+ }
+ finalizeNode(&group)
+ return group, true
+}
+
+// ---------- MySQL: EXPLAIN ANALYZE (tree text) ----------
+
+var (
+ treeLineRe = regexp.MustCompile(`^(\s*)->\s*(.*)$`)
+ treeCostRe = regexp.MustCompile(`\(cost=([0-9.eE+-]+)(?:\.\.([0-9.eE+-]+))?\s+rows=([0-9.eE+-]+)\)`)
+ treeActualRe = regexp.MustCompile(`\(actual time=([0-9.eE+-]+)\.\.([0-9.eE+-]+)\s+rows=([0-9.eE+-]+)\s+loops=([0-9.eE+-]+)\)`)
+ treeNeverRe = regexp.MustCompile(`\(never executed\)`)
+ treeOnRe = regexp.MustCompile(`\bon\s+([^\s(]+)`)
+ treeUsingRe = regexp.MustCompile(`\busing\s+([^\s(]+)`)
+)
+
+func parseMySQLTreePlan(plan *QueryPlan) {
+ var roots []*planBuilder
+ type frame struct {
+ indent int
+ builder *planBuilder
+ }
+ var stack []frame
+ for _, line := range strings.Split(plan.Raw, "\n") {
+ if strings.TrimSpace(line) == "" {
+ continue
+ }
+ indent, text := treeLineParts(line)
+ builder := &planBuilder{node: treeNode(text)}
+ for len(stack) > 0 && stack[len(stack)-1].indent >= indent {
+ stack = stack[:len(stack)-1]
+ }
+ if len(stack) == 0 {
+ roots = append(roots, builder)
+ } else {
+ parent := stack[len(stack)-1].builder
+ parent.children = append(parent.children, builder)
+ }
+ stack = append(stack, frame{indent: indent, builder: builder})
+ }
+ plan.Nodes = finishAll(roots)
+ if len(plan.Nodes) > 0 {
+ plan.TotalCost = plan.Nodes[0].CostTotal
+ plan.ExecutionMs = plan.Nodes[0].TimeMs
+ }
+}
+
+// A line without the "-> " marker belongs to the root, at indent 0.
+func treeLineParts(line string) (int, string) {
+ if m := treeLineRe.FindStringSubmatch(line); m != nil {
+ return len(m[1]), strings.TrimSpace(m[2])
+ }
+ return 0, strings.TrimSpace(line)
+}
+
+func treeNode(text string) PlanNode {
+ n := PlanNode{}
+ if m := treeCostRe.FindStringSubmatch(text); m != nil {
+ n.CostTotal = parseFloatPtr(m[1])
+ n.RowsPlanned = parseFloatPtr(m[3])
+ text = strings.Replace(text, m[0], "", 1)
+ }
+ if m := treeActualRe.FindStringSubmatch(text); m != nil {
+ loops := 1.0
+ if v, err := strconv.ParseFloat(m[4], 64); err == nil {
+ n.Loops = ptrFloat(v)
+ loops = v
+ }
+ // first-row and last-row, both per loop.
+ if v, err := strconv.ParseFloat(m[2], 64); err == nil {
+ n.TimeMs = ptrFloat(v * loops)
+ }
+ if v, err := strconv.ParseFloat(m[3], 64); err == nil {
+ n.RowsActual = ptrFloat(v * loops)
+ }
+ text = strings.Replace(text, m[0], "", 1)
+ }
+ if loc := treeNeverRe.FindString(text); loc != "" {
+ n.NeverRun = true
+ text = strings.Replace(text, loc, "", 1)
+ }
+ n.Label, n.Detail = splitLabelDetail(strings.TrimSpace(text))
+ // Read these off the operation only: a filter clause can contain "on" or "using".
+ if m := treeOnRe.FindStringSubmatch(n.Label); m != nil {
+ n.Relation = m[1]
+ }
+ if m := treeUsingRe.FindStringSubmatch(n.Label); m != nil {
+ n.Index = m[1]
+ }
+ return n
+}
+
+func splitLabelDetail(text string) (string, string) {
+ idx := strings.Index(text, ": ")
+ if idx <= 0 {
+ return text, ""
+ }
+ return strings.TrimSpace(text[:idx]), strings.TrimSpace(text[idx+2:])
+}
+
+// ---------- SQLite: EXPLAIN QUERY PLAN ----------
+
+var (
+ sqliteScanRe = regexp.MustCompile(`(?i)^(SCAN|SEARCH)\s+(?:TABLE\s+|SUBQUERY\s+)?(\S+)\s*(.*)$`)
+ sqliteIndexRe = regexp.MustCompile(`(?i)\bUSING\s+(?:COVERING\s+)?(?:AUTOMATIC\s+)?(?:PARTIAL\s+)?INDEX\s+([^\s(]+)`)
+)
+
+// parseSQLitePlan rebuilds the tree from the id/parent columns. SQLite reports plan shape only.
+func parseSQLitePlan(plan *QueryPlan, res *QueryResult) {
+ idID := columnIndex(res, "id", 0)
+ idParent := columnIndex(res, "parent", 1)
+ idDetail := columnIndex(res, "detail", 3)
+
+ byID := map[int64]*planBuilder{}
+ var roots []*planBuilder
+ var raw strings.Builder
+ for _, row := range res.Rows {
+ id, _ := planFloat(cellAt(row, idID))
+ parent, _ := planFloat(cellAt(row, idParent))
+ detail := planString(cellAt(row, idDetail))
+ builder := &planBuilder{node: sqliteNode(detail)}
+ byID[int64(id)] = builder
+ if p, ok := byID[int64(parent)]; ok && int64(parent) != int64(id) {
+ p.children = append(p.children, builder)
+ } else {
+ roots = append(roots, builder)
+ }
+ fmt.Fprintf(&raw, "%d|%d|%s\n", int64(id), int64(parent), detail)
+ }
+ plan.Nodes = finishAll(roots)
+ plan.Raw = strings.TrimRight(raw.String(), "\n")
+ plan.AddNote(PlanNoteNoMetrics)
+}
+
+func sqliteNode(detail string) PlanNode {
+ m := sqliteScanRe.FindStringSubmatch(strings.TrimSpace(detail))
+ if m == nil {
+ return PlanNode{Label: detail}
+ }
+ n := PlanNode{
+ Label: strings.ToUpper(m[1]),
+ Relation: m[2],
+ Detail: strings.TrimSpace(m[3]),
+ }
+ if idx := sqliteIndexRe.FindStringSubmatch(n.Detail); idx != nil {
+ n.Index = idx[1]
+ }
+ return n
+}
+
+// ---------- value helpers ----------
+
+// planFields renders the engine's remaining scalars, skipping skip and alsoSkip (the detail key).
+// Nested objects and arrays of objects are children, not fields.
+func planFields(raw map[string]any, skip map[string]bool, alsoSkip string) []PlanField {
+ var fields []PlanField
+ for _, key := range sortedKeys(raw) {
+ if skip[key] || (alsoSkip != "" && key == alsoSkip) {
+ continue
+ }
+ switch v := raw[key].(type) {
+ case nil, map[string]any:
+ continue
+ case []any:
+ if len(asObjectSlice(v)) > 0 {
+ continue
+ }
+ if s := planString(v); s != "" {
+ fields = append(fields, PlanField{Key: humanizeKey(key), Value: s})
+ }
+ default:
+ if s := planString(v); s != "" {
+ fields = append(fields, PlanField{Key: humanizeKey(key), Value: s})
+ }
+ }
+ }
+ return fields
+}
+
+func planString(v any) string {
+ switch val := v.(type) {
+ case nil:
+ return ""
+ case string:
+ return val
+ case bool:
+ return strconv.FormatBool(val)
+ case float64:
+ return strconv.FormatFloat(val, 'g', -1, 64)
+ case float32:
+ return strconv.FormatFloat(float64(val), 'g', -1, 32)
+ case int64:
+ return strconv.FormatInt(val, 10)
+ case int:
+ return strconv.Itoa(val)
+ case json.Number:
+ return val.String()
+ case []any:
+ parts := make([]string, 0, len(val))
+ for _, item := range val {
+ if s := planString(item); s != "" {
+ parts = append(parts, s)
+ }
+ }
+ return strings.Join(parts, ", ")
+ default:
+ return fmt.Sprintf("%v", val)
+ }
+}
+
+// The engines mix JSON numbers, quoted numbers ("1.35") and driver integer types.
+func planFloat(v any) (float64, bool) {
+ switch val := v.(type) {
+ case float64:
+ return val, true
+ case float32:
+ return float64(val), true
+ case int64:
+ return float64(val), true
+ case int:
+ return float64(val), true
+ case json.Number:
+ f, err := val.Float64()
+ return f, err == nil
+ case string:
+ f, err := strconv.ParseFloat(strings.TrimSpace(val), 64)
+ return f, err == nil
+ default:
+ return 0, false
+ }
+}
+
+func optFloat(v any) *float64 {
+ if f, ok := planFloat(v); ok {
+ return &f
+ }
+ return nil
+}
+
+func firstFloat(values ...any) *float64 {
+ for _, v := range values {
+ if f := optFloat(v); f != nil {
+ return f
+ }
+ }
+ return nil
+}
+
+func firstStringField(raw map[string]any, keys []string) (string, string) {
+ for _, key := range keys {
+ if v := planString(raw[key]); v != "" {
+ return key, v
+ }
+ }
+ return "", ""
+}
+
+func parseFloatPtr(s string) *float64 {
+ f, err := strconv.ParseFloat(s, 64)
+ if err != nil {
+ return nil
+ }
+ return &f
+}
+
+func ptrFloat(f float64) *float64 { return &f }
+
+func firstNonEmpty(values ...string) string {
+ for _, v := range values {
+ if v != "" {
+ return v
+ }
+ }
+ return ""
+}
+
+func asObjectSlice(v any) []map[string]any {
+ arr, ok := v.([]any)
+ if !ok {
+ return nil
+ }
+ var out []map[string]any
+ for _, item := range arr {
+ if obj, ok := item.(map[string]any); ok {
+ out = append(out, obj)
+ }
+ }
+ return out
+}
+
+func soleObjectEntry(obj map[string]any) (string, map[string]any, bool) {
+ if len(obj) != 1 {
+ return "", nil, false
+ }
+ for key, value := range obj {
+ if inner, ok := value.(map[string]any); ok {
+ return key, inner, true
+ }
+ }
+ return "", nil, false
+}
+
+func humanizeKey(key string) string {
+ if key == "" {
+ return ""
+ }
+ spaced := strings.NewReplacer("_", " ", "-", " ").Replace(key)
+ return strings.ToUpper(spaced[:1]) + spaced[1:]
+}
+
+func firstCell(res *QueryResult) any {
+ if res == nil || len(res.Rows) == 0 || len(res.Rows[0]) == 0 {
+ return nil
+ }
+ return res.Rows[0][0]
+}
+
+// Both JSON formats arrive as one row; MySQL tree text as one row of newline-separated lines.
+func joinFirstColumn(res *QueryResult) string {
+ if res == nil {
+ return ""
+ }
+ parts := make([]string, 0, len(res.Rows))
+ for _, row := range res.Rows {
+ if len(row) == 0 {
+ continue
+ }
+ parts = append(parts, planString(row[0]))
+ }
+ return strings.Join(parts, "\n")
+}
+
+func columnIndex(res *QueryResult, name string, fallback int) int {
+ for i, col := range res.Columns {
+ if strings.EqualFold(col, name) {
+ return i
+ }
+ }
+ return fallback
+}
+
+func cellAt(row []any, index int) any {
+ if index < 0 || index >= len(row) {
+ return nil
+ }
+ return row[index]
+}
diff --git a/internal/database/explain_test.go b/internal/database/explain_test.go
new file mode 100644
index 0000000..e5ec24f
--- /dev/null
+++ b/internal/database/explain_test.go
@@ -0,0 +1,784 @@
+package database
+
+import (
+ "math"
+ "strings"
+ "testing"
+)
+
+func TestParseServerVersion(t *testing.T) {
+ tests := []struct {
+ raw string
+ mariaDB bool
+ major int
+ minor int
+ patch int
+ }{
+ {"8.0.36", false, 8, 0, 36},
+ {"8.0.18-log", false, 8, 0, 18},
+ {"9.1.0", false, 9, 1, 0},
+ {"5.7.44-log", false, 5, 7, 44},
+ {"11.4.2-MariaDB-ubu2404", true, 11, 4, 2},
+ {"5.5.5-10.6.12-MariaDB-1:10.6.12+maria~ubu2004", true, 10, 6, 12},
+ {"", false, 0, 0, 0},
+ }
+ for _, tc := range tests {
+ got := ParseServerVersion(tc.raw)
+ if got.MariaDB != tc.mariaDB || got.Major != tc.major || got.Minor != tc.minor || got.Patch != tc.patch {
+ t.Errorf("ParseServerVersion(%q) = %+v, want mariadb=%v %d.%d.%d",
+ tc.raw, got, tc.mariaDB, tc.major, tc.minor, tc.patch)
+ }
+ }
+}
+
+func TestServerVersionAtLeast(t *testing.T) {
+ tests := []struct {
+ raw string
+ want bool
+ }{
+ {"8.0.18", true},
+ {"8.0.36", true},
+ {"8.4.0", true},
+ {"9.0.0", true},
+ {"8.0.17", false},
+ {"5.7.44", false},
+ {"8.0.2", false},
+ }
+ for _, tc := range tests {
+ if got := ParseServerVersion(tc.raw).atLeast(8, 0, 18); got != tc.want {
+ t.Errorf("%s atLeast(8.0.18) = %v, want %v", tc.raw, got, tc.want)
+ }
+ }
+}
+
+func TestBuildExplainSQL(t *testing.T) {
+ mysql8 := ParseServerVersion("8.0.36")
+ mysql57 := ParseServerVersion("5.7.44")
+ maria := ParseServerVersion("11.4.2-MariaDB")
+
+ tests := []struct {
+ name string
+ driver DriverType
+ sv ServerVersion
+ stmt string
+ analyze bool
+ want string
+ wantErr bool
+ }{
+ {name: "postgres plan", driver: DriverPostgres, stmt: "SELECT 1", want: "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {
+ name: "postgres analyze", driver: DriverPostgres, stmt: "SELECT 1", analyze: true,
+ want: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT 1",
+ },
+ {name: "mysql plan", driver: DriverMySQL, sv: mysql8, stmt: "SELECT 1", want: "EXPLAIN FORMAT=JSON SELECT 1"},
+ {
+ name: "mysql analyze uses tree", driver: DriverMySQL, sv: mysql8, stmt: "SELECT 1", analyze: true,
+ want: "EXPLAIN ANALYZE SELECT 1",
+ },
+ {
+ name: "mariadb analyze", driver: DriverMySQL, sv: maria, stmt: "SELECT 1", analyze: true,
+ want: "ANALYZE FORMAT=JSON SELECT 1",
+ },
+ {name: "mysql 5.7 cannot analyze", driver: DriverMySQL, sv: mysql57, stmt: "SELECT 1", analyze: true, wantErr: true},
+ {name: "sqlite plan", driver: DriverSQLite, stmt: "SELECT 1", want: "EXPLAIN QUERY PLAN SELECT 1"},
+ {name: "sqlite cannot analyze", driver: DriverSQLite, stmt: "SELECT 1", analyze: true, wantErr: true},
+ {name: "empty statement", driver: DriverPostgres, stmt: " ", wantErr: true},
+ {name: "unknown driver", driver: DriverType("oracle"), stmt: "SELECT 1", wantErr: true},
+ {
+ name: "trailing semicolon dropped", driver: DriverPostgres, stmt: "SELECT 1; ",
+ want: "EXPLAIN (FORMAT JSON) SELECT 1",
+ },
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ got, err := BuildExplainSQL(tc.driver, tc.sv, tc.stmt, tc.analyze)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("expected an error, got %q", got)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if got != tc.want {
+ t.Errorf("got %q, want %q", got, tc.want)
+ }
+ })
+ }
+}
+
+// A typed EXPLAIN is replaced, not nested.
+func TestBuildExplainSQLStripsExistingExplain(t *testing.T) {
+ tests := []struct {
+ driver DriverType
+ stmt string
+ want string
+ }{
+ {DriverPostgres, "EXPLAIN SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {DriverPostgres, "EXPLAIN ANALYZE SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {DriverPostgres, "explain (analyze, buffers) select 1", "EXPLAIN (FORMAT JSON) select 1"},
+ {DriverPostgres, "EXPLAIN (FORMAT TEXT) WITH x AS (SELECT 1) SELECT * FROM x", "EXPLAIN (FORMAT JSON) WITH x AS (SELECT 1) SELECT * FROM x"},
+ {DriverMySQL, "EXPLAIN FORMAT=JSON SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {DriverMySQL, "EXPLAIN ANALYZE SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {DriverMySQL, "ANALYZE FORMAT=JSON SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {DriverSQLite, "EXPLAIN QUERY PLAN SELECT 1", "EXPLAIN QUERY PLAN SELECT 1"},
+ // Not an explain of a statement: left alone.
+ {DriverMySQL, "ANALYZE TABLE t", "EXPLAIN FORMAT=JSON ANALYZE TABLE t"},
+ {DriverPostgres, "EXPLAIN", "EXPLAIN (FORMAT JSON) EXPLAIN"},
+ }
+ for _, tc := range tests {
+ got, err := BuildExplainSQL(tc.driver, ServerVersion{}, tc.stmt, false)
+ if err != nil {
+ t.Fatalf("%s %q: %v", tc.driver, tc.stmt, err)
+ }
+ if got != tc.want {
+ t.Errorf("%s %q: got %q, want %q", tc.driver, tc.stmt, got, tc.want)
+ }
+ }
+}
+
+func TestSingleStatement(t *testing.T) {
+ if got, err := SingleStatement(DriverPostgres, " SELECT 1; "); err != nil || got != "SELECT 1" {
+ t.Errorf("single: got %q, %v", got, err)
+ }
+ if _, err := SingleStatement(DriverPostgres, "SELECT 1; SELECT 2"); err == nil {
+ t.Error("expected an error for two statements")
+ }
+ if _, err := SingleStatement(DriverPostgres, " -- just a comment\n"); err == nil {
+ t.Error("expected an error for no statement")
+ }
+}
+
+// ---------- Postgres ----------
+
+const pgAnalyzeJSON = `[
+ {
+ "Plan": {
+ "Node Type": "Nested Loop",
+ "Parallel Aware": false,
+ "Join Type": "Inner",
+ "Startup Cost": 0.29,
+ "Total Cost": 42.58,
+ "Plan Rows": 10,
+ "Plan Width": 68,
+ "Actual Startup Time": 0.021,
+ "Actual Total Time": 0.185,
+ "Actual Rows": 9,
+ "Actual Loops": 1,
+ "Plans": [
+ {
+ "Node Type": "Seq Scan",
+ "Parent Relationship": "Outer",
+ "Relation Name": "orders",
+ "Alias": "o",
+ "Startup Cost": 0.00,
+ "Total Cost": 18.10,
+ "Plan Rows": 10,
+ "Plan Width": 36,
+ "Actual Startup Time": 0.010,
+ "Actual Total Time": 0.032,
+ "Actual Rows": 9,
+ "Actual Loops": 1,
+ "Filter": "(total > 100)",
+ "Rows Removed by Filter": 3,
+ "Shared Hit Blocks": 5
+ },
+ {
+ "Node Type": "Index Scan",
+ "Parent Relationship": "Inner",
+ "Relation Name": "customers",
+ "Alias": "c",
+ "Index Name": "customers_pkey",
+ "Startup Cost": 0.29,
+ "Total Cost": 2.44,
+ "Plan Rows": 1,
+ "Plan Width": 32,
+ "Actual Startup Time": 0.003,
+ "Actual Total Time": 0.004,
+ "Actual Rows": 1,
+ "Actual Loops": 9,
+ "Index Cond": "(id = o.customer_id)"
+ }
+ ]
+ },
+ "Planning Time": 0.153,
+ "Execution Time": 0.221
+ }
+]`
+
+func TestParsePostgresAnalyzePlan(t *testing.T) {
+ plan := parsePlanFixture(t, DriverPostgres, true, pgAnalyzeJSON)
+
+ if len(plan.Nodes) != 1 {
+ t.Fatalf("expected 1 root, got %d", len(plan.Nodes))
+ }
+ wantFloat(t, "planning ms", plan.PlanningMs, 0.153)
+ wantFloat(t, "execution ms", plan.ExecutionMs, 0.221)
+ wantFloat(t, "total cost", plan.TotalCost, 42.58)
+ if plan.Notes != nil {
+ t.Errorf("an analyzed plan needs no notes, got %v", plan.Notes)
+ }
+
+ root := plan.Nodes[0]
+ if root.Label != "Nested Loop" {
+ t.Errorf("root label = %q", root.Label)
+ }
+ wantFloat(t, "root time", root.TimeMs, 0.185)
+ wantFloat(t, "root rows", root.RowsActual, 9)
+ wantFloat(t, "root self time", root.SelfTimeMs, 0.185-(0.032+0.036))
+ wantFloat(t, "root self cost", root.CostSelf, 42.58-(18.10+2.44))
+ if len(root.Children) != 2 {
+ t.Fatalf("expected 2 children, got %d", len(root.Children))
+ }
+
+ seq := root.Children[0]
+ if seq.Label != "Seq Scan" || seq.Relation != "orders o" {
+ t.Errorf("seq scan = %q on %q", seq.Label, seq.Relation)
+ }
+ if seq.Detail != "(total > 100)" {
+ t.Errorf("seq scan detail = %q", seq.Detail)
+ }
+ wantFloat(t, "seq scan cost", seq.CostTotal, 18.10)
+ wantFloat(t, "seq scan self cost", seq.CostSelf, 18.10)
+ if hasField(seq.Fields, "Filter") {
+ t.Error("the detail clause should not repeat in the field list")
+ }
+ if got := fieldValue(seq.Fields, "Rows Removed by Filter"); got != "3" {
+ t.Errorf("rows removed by filter = %q", got)
+ }
+ if got := fieldValue(seq.Fields, "Shared Hit Blocks"); got != "5" {
+ t.Errorf("shared hit blocks = %q", got)
+ }
+
+ idx := root.Children[1]
+ if idx.Index != "customers_pkey" || idx.Detail != "(id = o.customer_id)" {
+ t.Errorf("index scan = %+v", idx)
+ }
+ // Per-loop averages: 9 loops of 1 row at 0.004ms is 9 rows in 0.036ms.
+ wantFloat(t, "index scan loops", idx.Loops, 9)
+ wantFloat(t, "index scan rows", idx.RowsActual, 9)
+ wantFloat(t, "index scan time", idx.TimeMs, 0.036)
+}
+
+func TestParsePostgresPlanOnly(t *testing.T) {
+ const raw = `[{"Plan":{"Node Type":"Seq Scan","Relation Name":"t","Alias":"t","Total Cost":12.5,"Plan Rows":420,"Plan Width":8}}]`
+ plan := parsePlanFixture(t, DriverPostgres, false, raw)
+
+ root := plan.Nodes[0]
+ if root.TimeMs != nil || root.RowsActual != nil || root.Loops != nil {
+ t.Errorf("a plan-only run must carry no measurements: %+v", root)
+ }
+ wantFloat(t, "rows planned", root.RowsPlanned, 420)
+ if len(plan.Notes) != 0 {
+ t.Errorf("expected no notes, got %v", plan.Notes)
+ }
+}
+
+func TestPostgresLabels(t *testing.T) {
+ tests := []struct {
+ raw string
+ want string
+ }{
+ {`{"Node Type":"Hash Join","Join Type":"Left"}`, "Hash Join (Left)"},
+ {`{"Node Type":"Hash Join","Join Type":"Inner"}`, "Hash Join"},
+ {`{"Node Type":"Aggregate","Strategy":"Hashed"}`, "Aggregate (Hashed)"},
+ {`{"Node Type":"Aggregate","Strategy":"Plain"}`, "Aggregate"},
+ {`{"Node Type":"Seq Scan","Parallel Aware":true}`, "Parallel Seq Scan"},
+ {`{"Node Type":"Aggregate","Subplan Name":"InitPlan 1 (returns $0)"}`, "InitPlan 1 (returns $0): Aggregate"},
+ {`{}`, "Node"},
+ }
+ for _, tc := range tests {
+ plan := parsePlanFixture(t, DriverPostgres, false, `[{"Plan":`+tc.raw+`}]`)
+ if got := plan.Nodes[0].Label; got != tc.want {
+ t.Errorf("%s β %q, want %q", tc.raw, got, tc.want)
+ }
+ }
+}
+
+// A subplan's time is outside its parent's total, so the subtraction must not go negative.
+func TestPostgresSelfTimeNeverNegative(t *testing.T) {
+ const raw = `[{"Plan":{
+ "Node Type":"Result","Total Cost":1.0,"Actual Total Time":0.05,"Actual Loops":1,
+ "Plans":[{"Node Type":"Aggregate","Subplan Name":"InitPlan 1","Total Cost":9.0,"Actual Total Time":0.4,"Actual Loops":1}]
+ }}]`
+ plan := parsePlanFixture(t, DriverPostgres, true, raw)
+ wantFloat(t, "self time", plan.Nodes[0].SelfTimeMs, 0)
+ wantFloat(t, "self cost", plan.Nodes[0].CostSelf, 0)
+}
+
+func TestPostgresNeverExecuted(t *testing.T) {
+ const raw = `[{"Plan":{"Node Type":"Result","Total Cost":1,"Actual Total Time":0,"Actual Rows":0,"Actual Loops":0}}]`
+ plan := parsePlanFixture(t, DriverPostgres, true, raw)
+ if !plan.Nodes[0].NeverRun {
+ t.Error("expected the node to be marked as never run")
+ }
+}
+
+func TestParsePostgresPlanRejectsGarbage(t *testing.T) {
+ res := &QueryResult{Columns: []string{"QUERY PLAN"}, Rows: [][]any{{"not json"}}}
+ if _, err := ParsePlan(DriverPostgres, "SELECT 1", "EXPLAIN β¦", false, res); err == nil {
+ t.Fatal("expected an error for non-JSON output")
+ }
+}
+
+// ---------- MySQL ----------
+
+const mysqlJSON = `{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {"query_cost": "3.60"},
+ "nested_loop": [
+ {
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 10,
+ "rows_produced_per_join": 3,
+ "filtered": "33.33",
+ "cost_info": {"read_cost": "1.25", "eval_cost": "0.33", "prefix_cost": "1.58", "data_read_per_join": "160"},
+ "used_columns": ["id", "customer_id", "total"],
+ "attached_condition": "(` + "`shop`.`o`.`total`" + ` > 100)"
+ }
+ },
+ {
+ "table": {
+ "table_name": "c",
+ "access_type": "eq_ref",
+ "possible_keys": ["PRIMARY"],
+ "key": "PRIMARY",
+ "used_key_parts": ["id"],
+ "key_length": "4",
+ "ref": ["shop.o.customer_id"],
+ "rows_examined_per_scan": 1,
+ "rows_produced_per_join": 3,
+ "filtered": "100.00",
+ "cost_info": {"read_cost": "1.69", "eval_cost": "0.33", "prefix_cost": "3.60", "data_read_per_join": "192"}
+ }
+ }
+ ]
+ }
+}`
+
+func TestParseMySQLJSONPlan(t *testing.T) {
+ plan := parsePlanFixture(t, DriverMySQL, false, mysqlJSON)
+
+ if len(plan.Nodes) != 1 {
+ t.Fatalf("expected 1 root, got %d", len(plan.Nodes))
+ }
+ root := plan.Nodes[0]
+ if root.Label != "Query block #1" {
+ t.Errorf("root label = %q", root.Label)
+ }
+ wantFloat(t, "total cost", plan.TotalCost, 3.60)
+
+ if len(root.Children) != 1 {
+ t.Fatalf("expected the nested loop group, got %d children", len(root.Children))
+ }
+ group := root.Children[0]
+ if group.Label != "Nested loop" {
+ t.Errorf("group label = %q", group.Label)
+ }
+ // Sum of the tables' own costs, not of MySQL's cumulative prefix_cost.
+ wantFloat(t, "join cost", group.CostTotal, 3.60)
+ if len(group.Children) != 2 {
+ t.Fatalf("expected 2 tables, got %d", len(group.Children))
+ }
+
+ outer := group.Children[0]
+ if outer.Label != "Table (ALL)" || outer.Relation != "o" {
+ t.Errorf("outer = %q on %q", outer.Label, outer.Relation)
+ }
+ if !strings.Contains(outer.Detail, "> 100") {
+ t.Errorf("outer detail = %q", outer.Detail)
+ }
+ wantFloat(t, "outer rows", outer.RowsPlanned, 3)
+ wantFloat(t, "outer self cost", outer.CostSelf, 1.58)
+ // cost_info's other numbers survive the fold.
+ if got := fieldValue(outer.Fields, "Prefix cost"); got != "1.58" {
+ t.Errorf("prefix cost field = %q", got)
+ }
+ if got := fieldValue(outer.Fields, "Rows examined per scan"); got != "10" {
+ t.Errorf("rows examined field = %q", got)
+ }
+ if got := fieldValue(outer.Fields, "Used columns"); got != "id, customer_id, total" {
+ t.Errorf("used columns field = %q", got)
+ }
+
+ inner := group.Children[1]
+ if inner.Label != "Table (eq_ref)" || inner.Index != "PRIMARY" {
+ t.Errorf("inner = %q using %q", inner.Label, inner.Index)
+ }
+ wantFloat(t, "inner self cost", inner.CostSelf, 2.02)
+ if inner.TimeMs != nil {
+ t.Errorf("EXPLAIN without ANALYZE has no timings, got %v", *inner.TimeMs)
+ }
+}
+
+const mariaAnalyzeJSON = `{
+ "query_block": {
+ "select_id": 1,
+ "r_loops": 1,
+ "r_total_time_ms": 0.4521,
+ "nested_loop": [
+ {
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "r_loops": 1,
+ "rows": 10,
+ "r_rows": 9,
+ "r_table_time_ms": 0.0521,
+ "r_other_time_ms": 0.0129,
+ "filtered": 100,
+ "r_filtered": 90,
+ "attached_condition": "o.total > 100"
+ }
+ },
+ {
+ "table": {
+ "table_name": "c",
+ "access_type": "eq_ref",
+ "possible_keys": ["PRIMARY"],
+ "key": "PRIMARY",
+ "r_loops": 9,
+ "rows": 1,
+ "r_rows": 1,
+ "r_table_time_ms": 0.1521,
+ "r_other_time_ms": 0.0221
+ }
+ }
+ ]
+ }
+}`
+
+func TestParseMariaDBAnalyzePlan(t *testing.T) {
+ plan := parsePlanFixture(t, DriverMySQL, true, mariaAnalyzeJSON)
+
+ root := plan.Nodes[0]
+ wantFloat(t, "root time", root.TimeMs, 0.4521)
+ wantFloat(t, "execution ms", plan.ExecutionMs, 0.4521)
+
+ group := root.Children[0]
+ outer := group.Children[0]
+ // MariaDB splits table and other time; together they are the node's own.
+ wantFloat(t, "outer self time", outer.SelfTimeMs, 0.065)
+ wantFloat(t, "outer rows planned", outer.RowsPlanned, 10)
+ wantFloat(t, "outer rows actual", outer.RowsActual, 9)
+
+ inner := group.Children[1]
+ wantFloat(t, "inner loops", inner.Loops, 9)
+ wantFloat(t, "inner rows actual", inner.RowsActual, 9)
+ wantFloat(t, "inner self time", inner.SelfTimeMs, 0.1742)
+
+ wantFloat(t, "join time", group.TimeMs, 0.065+0.1742)
+ wantFloat(t, "root self time", root.SelfTimeMs, 0.4521-(0.065+0.1742))
+}
+
+const mysqlTree = `-> Nested loop inner join (cost=3.60 rows=3) (actual time=0.0451..0.0912 rows=9 loops=1)
+ -> Filter: (o.total > 100) (cost=1.58 rows=3) (actual time=0.0312..0.0451 rows=9 loops=1)
+ -> Table scan on o (cost=1.58 rows=10) (actual time=0.0221..0.0356 rows=10 loops=1)
+ -> Single-row index lookup on c using PRIMARY (id=o.customer_id) (cost=0.67 rows=1) (actual time=0.0021..0.0024 rows=1 loops=9)
+`
+
+func TestParseMySQLTreePlan(t *testing.T) {
+ plan := parsePlanFixture(t, DriverMySQL, true, mysqlTree)
+
+ if len(plan.Nodes) != 1 {
+ t.Fatalf("expected 1 root, got %d", len(plan.Nodes))
+ }
+ root := plan.Nodes[0]
+ if root.Label != "Nested loop inner join" {
+ t.Errorf("root label = %q", root.Label)
+ }
+ wantFloat(t, "root cost", root.CostTotal, 3.60)
+ wantFloat(t, "root rows planned", root.RowsPlanned, 3)
+ wantFloat(t, "root time", root.TimeMs, 0.0912)
+ wantFloat(t, "root rows actual", root.RowsActual, 9)
+ if len(root.Children) != 2 {
+ t.Fatalf("expected 2 children, got %d", len(root.Children))
+ }
+
+ filter := root.Children[0]
+ if filter.Label != "Filter" || filter.Detail != "(o.total > 100)" {
+ t.Errorf("filter = %q / %q", filter.Label, filter.Detail)
+ }
+ if len(filter.Children) != 1 {
+ t.Fatalf("expected the scan under the filter, got %d children", len(filter.Children))
+ }
+ if scan := filter.Children[0]; scan.Relation != "o" {
+ t.Errorf("scan relation = %q", scan.Relation)
+ }
+
+ lookup := root.Children[1]
+ if lookup.Relation != "c" || lookup.Index != "PRIMARY" {
+ t.Errorf("lookup = %q using %q", lookup.Relation, lookup.Index)
+ }
+ wantFloat(t, "lookup time", lookup.TimeMs, 0.0216)
+ wantFloat(t, "lookup rows", lookup.RowsActual, 9)
+ wantFloat(t, "root self time", root.SelfTimeMs, 0.0912-(0.0451+0.0216))
+}
+
+func TestParseMySQLTreeNeverExecuted(t *testing.T) {
+ const raw = `-> Limit: 1 row(s) (cost=0.35 rows=1) (actual time=0.01..0.02 rows=1 loops=1)
+ -> Index lookup on t using ix (a=1) (cost=0.35 rows=1) (never executed)
+`
+ plan := parsePlanFixture(t, DriverMySQL, true, raw)
+ child := plan.Nodes[0].Children[0]
+ if !child.NeverRun {
+ t.Error("expected the child to be marked as never run")
+ }
+ if !strings.HasPrefix(child.Label, "Index lookup on t using ix") {
+ t.Errorf("label kept the marker: %q", child.Label)
+ }
+}
+
+func TestParseMySQLTreeIgnoresClauseKeywords(t *testing.T) {
+ const raw = `-> Filter: (t.status = 'on' and t.mode = 'using idx') (cost=1.0 rows=1)
+`
+ node := parsePlanFixture(t, DriverMySQL, false, raw).Nodes[0]
+ if node.Relation != "" || node.Index != "" {
+ t.Errorf("relation = %q, index = %q; both should be empty", node.Relation, node.Index)
+ }
+}
+
+// ---------- SQLite ----------
+
+func TestParseSQLitePlan(t *testing.T) {
+ res := &QueryResult{
+ Columns: []string{"id", "parent", "notused", "detail"},
+ Rows: [][]any{
+ {int64(4), int64(0), int64(0), "CO-ROUTINE t1"},
+ {int64(8), int64(4), int64(0), "SCAN x"},
+ {int64(20), int64(0), int64(0), "SEARCH c USING INDEX idx_c (a=?)"},
+ },
+ }
+ plan, err := ParsePlan(DriverSQLite, "SELECT 1", "EXPLAIN QUERY PLAN SELECT 1", false, res)
+ if err != nil {
+ t.Fatalf("ParsePlan: %v", err)
+ }
+ if len(plan.Nodes) != 2 {
+ t.Fatalf("expected 2 roots, got %d", len(plan.Nodes))
+ }
+
+ coroutine := plan.Nodes[0]
+ if coroutine.Label != "CO-ROUTINE t1" {
+ t.Errorf("coroutine label = %q", coroutine.Label)
+ }
+ if len(coroutine.Children) != 1 || coroutine.Children[0].Relation != "x" {
+ t.Fatalf("expected SCAN x nested under the coroutine, got %+v", coroutine.Children)
+ }
+ if coroutine.Children[0].Label != "SCAN" {
+ t.Errorf("child label = %q", coroutine.Children[0].Label)
+ }
+
+ search := plan.Nodes[1]
+ if search.Label != "SEARCH" || search.Relation != "c" || search.Index != "idx_c" {
+ t.Errorf("search = %+v", search)
+ }
+ if search.Detail != "USING INDEX idx_c (a=?)" {
+ t.Errorf("search detail = %q", search.Detail)
+ }
+ if search.CostTotal != nil || search.RowsPlanned != nil || search.TimeMs != nil {
+ t.Error("SQLite reports no cost, row or time estimates")
+ }
+ if !hasNote(plan, PlanNoteNoMetrics) {
+ t.Errorf("expected the no-metrics note, got %v", plan.Notes)
+ }
+ if plan.Raw != "4|0|CO-ROUTINE t1\n8|4|SCAN x\n20|0|SEARCH c USING INDEX idx_c (a=?)" {
+ t.Errorf("raw = %q", plan.Raw)
+ }
+}
+
+func TestParseSQLiteScanVariants(t *testing.T) {
+ tests := []struct {
+ detail string
+ label string
+ relation string
+ index string
+ }{
+ {"SCAN t", "SCAN", "t", ""},
+ {"SCAN TABLE t", "SCAN", "t", ""},
+ {"SEARCH t USING COVERING INDEX ix_t (a=?)", "SEARCH", "t", "ix_t"},
+ {"SEARCH t USING AUTOMATIC PARTIAL COVERING INDEX ix (a=?)", "SEARCH", "t", ""},
+ {"SEARCH t USING INTEGER PRIMARY KEY (rowid=?)", "SEARCH", "t", ""},
+ {"USE TEMP B-TREE FOR ORDER BY", "USE TEMP B-TREE FOR ORDER BY", "", ""},
+ }
+ for _, tc := range tests {
+ got := sqliteNode(tc.detail)
+ if got.Label != tc.label || got.Relation != tc.relation || got.Index != tc.index {
+ t.Errorf("%q β label %q relation %q index %q; want %q/%q/%q",
+ tc.detail, got.Label, got.Relation, got.Index, tc.label, tc.relation, tc.index)
+ }
+ }
+}
+
+func TestParsePlanRejectsEmptyResult(t *testing.T) {
+ if _, err := ParsePlan(DriverPostgres, "SELECT 1", "EXPLAIN β¦", false, nil); err == nil {
+ t.Error("expected an error for a nil result")
+ }
+ empty := &QueryResult{Columns: []string{"QUERY PLAN"}}
+ if _, err := ParsePlan(DriverPostgres, "SELECT 1", "EXPLAIN β¦", false, empty); err == nil {
+ t.Error("expected an error for a result with no rows")
+ }
+}
+
+// ---------- helpers ----------
+
+func parsePlanFixture(t *testing.T, driver DriverType, analyze bool, raw string) *QueryPlan {
+ t.Helper()
+ res := &QueryResult{Columns: []string{"EXPLAIN"}, Rows: [][]any{{raw}}}
+ plan, err := ParsePlan(driver, "SELECT 1", "EXPLAIN β¦", analyze, res)
+ if err != nil {
+ t.Fatalf("ParsePlan(%s): %v", driver, err)
+ }
+ if len(plan.Nodes) == 0 {
+ t.Fatalf("ParsePlan(%s) produced no nodes", driver)
+ }
+ return plan
+}
+
+func wantFloat(t *testing.T, what string, got *float64, want float64) {
+ t.Helper()
+ if got == nil {
+ t.Errorf("%s is missing, want %g", what, want)
+ return
+ }
+ if math.Abs(*got-want) > 1e-9 {
+ t.Errorf("%s = %g, want %g", what, *got, want)
+ }
+}
+
+func fieldValue(fields []PlanField, key string) string {
+ for _, f := range fields {
+ if f.Key == key {
+ return f.Value
+ }
+ }
+ return ""
+}
+
+func hasField(fields []PlanField, key string) bool {
+ for _, f := range fields {
+ if f.Key == key {
+ return true
+ }
+ }
+ return false
+}
+
+func hasNote(plan *QueryPlan, code string) bool {
+ for _, n := range plan.Notes {
+ if n == code {
+ return true
+ }
+ }
+ return false
+}
+
+// ---------- detecting a typed EXPLAIN ----------
+
+func TestDetectPlanRequestPostgres(t *testing.T) {
+ tests := []struct {
+ stmt string
+ wantSQL string
+ analyze bool
+ wantOK bool
+ }{
+ // Text output: asked again in JSON.
+ {stmt: "EXPLAIN SELECT 1", wantSQL: "EXPLAIN (FORMAT JSON) SELECT 1", wantOK: true},
+ {stmt: "EXPLAIN ANALYZE SELECT 1", wantSQL: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT 1", analyze: true, wantOK: true},
+ {stmt: "explain analyze verbose select 1", wantSQL: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) select 1", analyze: true, wantOK: true},
+ {stmt: "EXPLAIN (ANALYZE, BUFFERS) SELECT 1", wantSQL: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT 1", analyze: true, wantOK: true},
+ // Already JSON: run as typed.
+ {stmt: "EXPLAIN (FORMAT JSON) SELECT 1", wantSQL: "EXPLAIN (FORMAT JSON) SELECT 1", wantOK: true},
+ {stmt: "EXPLAIN (ANALYZE, FORMAT JSON) SELECT 1", wantSQL: "EXPLAIN (ANALYZE, FORMAT JSON) SELECT 1", analyze: true, wantOK: true},
+ {stmt: "EXPLAIN (ANALYZE false, FORMAT JSON) SELECT 1", wantSQL: "EXPLAIN (ANALYZE false, FORMAT JSON) SELECT 1", wantOK: true},
+ // A named format means raw output.
+ {stmt: "EXPLAIN (FORMAT TEXT) SELECT 1", wantOK: false},
+ {stmt: "EXPLAIN (FORMAT YAML) SELECT 1", wantOK: false},
+ {stmt: "EXPLAIN (ANALYZE, FORMAT XML) SELECT 1", wantOK: false},
+ {stmt: "SELECT 1", wantOK: false},
+ {stmt: "EXPLAIN", wantOK: false},
+ {stmt: "ANALYZE my_table", wantOK: false},
+ {stmt: "-- a comment\nEXPLAIN SELECT 1", wantSQL: "EXPLAIN (FORMAT JSON) SELECT 1", wantOK: true},
+ }
+ for _, tc := range tests {
+ got, ok := DetectPlanRequest(DriverPostgres, tc.stmt)
+ if ok != tc.wantOK {
+ t.Errorf("DetectPlanRequest(%q) ok = %v, want %v", tc.stmt, ok, tc.wantOK)
+ continue
+ }
+ if !ok {
+ continue
+ }
+ if got.SQL != tc.wantSQL || got.Analyze != tc.analyze {
+ t.Errorf("DetectPlanRequest(%q) = %q analyze=%v, want %q analyze=%v",
+ tc.stmt, got.SQL, got.Analyze, tc.wantSQL, tc.analyze)
+ }
+ }
+}
+
+func TestDetectPlanRequestMySQL(t *testing.T) {
+ tests := []struct {
+ stmt string
+ wantSQL string
+ analyze bool
+ wantOK bool
+ }{
+ // Traditional table: asked again in JSON.
+ {stmt: "EXPLAIN SELECT 1", wantSQL: "EXPLAIN FORMAT=JSON SELECT 1", wantOK: true},
+ // Tree output parses as-is.
+ {stmt: "EXPLAIN ANALYZE SELECT 1", wantSQL: "EXPLAIN ANALYZE SELECT 1", analyze: true, wantOK: true},
+ {stmt: "EXPLAIN FORMAT=JSON SELECT 1", wantSQL: "EXPLAIN FORMAT=JSON SELECT 1", wantOK: true},
+ {stmt: "EXPLAIN FORMAT=TREE SELECT 1", wantSQL: "EXPLAIN FORMAT=TREE SELECT 1", wantOK: true},
+ {stmt: "EXPLAIN ANALYZE FORMAT=JSON SELECT 1", wantSQL: "EXPLAIN ANALYZE FORMAT=JSON SELECT 1", analyze: true, wantOK: true},
+ {stmt: "ANALYZE FORMAT=JSON SELECT 1", wantSQL: "ANALYZE FORMAT=JSON SELECT 1", analyze: true, wantOK: true},
+ // Tabular: asked again in JSON, still measured.
+ {stmt: "ANALYZE SELECT 1", wantSQL: "ANALYZE FORMAT=JSON SELECT 1", analyze: true, wantOK: true},
+ {stmt: "EXPLAIN FORMAT=TRADITIONAL SELECT 1", wantOK: false},
+ // The statistics command.
+ {stmt: "ANALYZE TABLE users", wantOK: false},
+ {stmt: "EXPLAIN users", wantOK: false},
+ {stmt: "DESCRIBE users", wantOK: false},
+ }
+ for _, tc := range tests {
+ got, ok := DetectPlanRequest(DriverMySQL, tc.stmt)
+ if ok != tc.wantOK {
+ t.Errorf("DetectPlanRequest(%q) ok = %v, want %v", tc.stmt, ok, tc.wantOK)
+ continue
+ }
+ if !ok {
+ continue
+ }
+ if got.SQL != tc.wantSQL || got.Analyze != tc.analyze {
+ t.Errorf("DetectPlanRequest(%q) = %q analyze=%v, want %q analyze=%v",
+ tc.stmt, got.SQL, got.Analyze, tc.wantSQL, tc.analyze)
+ }
+ }
+}
+
+func TestDetectPlanRequestSQLite(t *testing.T) {
+ got, ok := DetectPlanRequest(DriverSQLite, "EXPLAIN QUERY PLAN SELECT 1")
+ if !ok || got.SQL != "EXPLAIN QUERY PLAN SELECT 1" || got.Analyze {
+ t.Errorf("EXPLAIN QUERY PLAN β %+v, ok=%v", got, ok)
+ }
+ // Bytecode, not a plan.
+ if _, ok := DetectPlanRequest(DriverSQLite, "EXPLAIN SELECT 1"); ok {
+ t.Error("SQLite's bytecode EXPLAIN must not be treated as a plan request")
+ }
+}
+
+// Run executes what you typed; the classifier only picks how to ask for the plan.
+func TestDetectPlanRequestKeepsWrites(t *testing.T) {
+ got, ok := DetectPlanRequest(DriverPostgres, "EXPLAIN ANALYZE DELETE FROM t")
+ if !ok {
+ t.Fatal("expected a plan request")
+ }
+ if !got.Analyze {
+ t.Error("expected the request to report that it executes")
+ }
+ if !strings.Contains(got.SQL, "DELETE FROM t") {
+ t.Errorf("inner statement lost: %q", got.SQL)
+ }
+}
diff --git a/internal/database/runscript_test.go b/internal/database/runscript_test.go
index f288049..9cf3617 100644
--- a/internal/database/runscript_test.go
+++ b/internal/database/runscript_test.go
@@ -29,6 +29,7 @@ type capturedSet struct {
cols []string
rows [][]any
summary *QueryResult
+ plan *QueryPlan
stmt string
err error
}
@@ -51,9 +52,10 @@ func captureSink(sets *[]*capturedSet) ScriptSink {
s.rows = append(s.rows, rows...)
return nil
},
- OnResult: func(idx int, summary *QueryResult, stmt string, err error) {
+ OnResult: func(idx int, summary *QueryResult, plan *QueryPlan, stmt string, err error) {
s := get(idx)
s.summary = summary
+ s.plan = plan
s.stmt = stmt
s.err = err
*sets = append(*sets, s)
@@ -122,3 +124,75 @@ func TestRunScriptStopsAtFirstError(t *testing.T) {
t.Error("second set should carry the syntax error")
}
}
+
+// A typed EXPLAIN yields a plan; its neighbours stay grids.
+func TestRunScriptMixesPlansAndGrids(t *testing.T) {
+ conn, cleanup := memConn(t)
+ defer cleanup()
+
+ var sets []*capturedSet
+ script := []string{
+ "CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)",
+ "INSERT INTO t VALUES (1, 'a'), (2, 'b')",
+ "SELECT * FROM t",
+ "EXPLAIN QUERY PLAN SELECT * FROM t WHERE id = 1",
+ "SELECT COUNT(*) FROM t",
+ }
+ if err := RunScript(context.Background(), conn, DriverSQLite, script, captureSink(&sets)); err != nil {
+ t.Fatalf("RunScript: %v", err)
+ }
+ if len(sets) != 5 {
+ t.Fatalf("expected one result set per statement, got %d", len(sets))
+ }
+
+ plan := sets[3]
+ if plan.plan == nil {
+ t.Fatalf("the EXPLAIN statement produced no plan: %+v", plan)
+ }
+ if len(plan.rows) != 0 {
+ t.Errorf("a plan set must deliver no rows, got %d", len(plan.rows))
+ }
+ if plan.summary != nil {
+ t.Errorf("a plan set carries no row summary, got %+v", plan.summary)
+ }
+ if len(plan.plan.Nodes) == 0 {
+ t.Fatal("expected plan nodes")
+ }
+ if got := plan.plan.Nodes[0]; got.Label != "SEARCH" || got.Relation != "t" {
+ t.Errorf("plan root = %+v, expected a SEARCH of t", got)
+ }
+ if plan.plan.Analyzed {
+ t.Error("EXPLAIN QUERY PLAN measures nothing")
+ }
+
+ for _, i := range []int{2, 4} {
+ if sets[i].plan != nil {
+ t.Errorf("set %d should be a grid, got a plan", i)
+ }
+ if len(sets[i].rows) == 0 {
+ t.Errorf("set %d should have rows", i)
+ }
+ }
+}
+
+// Bytecode, not a plan: it stays an ordinary query.
+func TestRunScriptKeepsSQLiteBytecodeExplainAsRows(t *testing.T) {
+ conn, cleanup := memConn(t)
+ defer cleanup()
+
+ var sets []*capturedSet
+ script := []string{
+ "CREATE TABLE t (id INTEGER PRIMARY KEY)",
+ "EXPLAIN SELECT * FROM t",
+ }
+ if err := RunScript(context.Background(), conn, DriverSQLite, script, captureSink(&sets)); err != nil {
+ t.Fatalf("RunScript: %v", err)
+ }
+ last := sets[len(sets)-1]
+ if last.plan != nil {
+ t.Error("bytecode EXPLAIN must not become a plan")
+ }
+ if len(last.rows) == 0 {
+ t.Error("expected the bytecode listing as rows")
+ }
+}