diff --git a/agents/drivers/xugu/explain_live_test.go b/agents/drivers/xugu/explain_live_test.go new file mode 100644 index 0000000000..114a5afbbf --- /dev/null +++ b/agents/drivers/xugu/explain_live_test.go @@ -0,0 +1,65 @@ +package main + +import ( + "fmt" + "os" + "strings" + "testing" +) + +// Read-only opt-in coverage of the exact query path used by the visual plan. +// Run for SYSTEM/business databases and ordinary/DBA/SYSDBA users using the +// existing XUGU_LIVE_* settings. It creates no objects and changes no grants. +func TestLiveXuguExplain(t *testing.T) { + if os.Getenv("XUGU_LIVE_TEST") != "1" { + t.Skip("set XUGU_LIVE_TEST=1 with XUGU_LIVE_* settings") + } + params := liveXuguParams(t) + db, err := openDB(params) + if err != nil { + t.Fatalf("open live Xugu connection: %v", err) + } + s := newServer() + s.db, s.params, s.currentDatabase = db, params, params.Database + t.Cleanup(func() { _ = s.disconnect() }) + if err := s.validateConnection(); err != nil { + t.Fatalf("validate connection: %v", err) + } + schema, err := s.currentSchema() + if err != nil { + t.Fatalf("current schema: %v", err) + } + + for name, sql := range map[string]string{ + "constant": "SELECT 1 FROM DUAL", + "filter": "SELECT TABLE_NAME FROM ALL_TABLES WHERE TABLE_NAME LIKE 'DBX%'", + "sort_limit": "SELECT TABLE_NAME FROM ALL_TABLES ORDER BY TABLE_NAME LIMIT 10", + "aggregate": "SELECT TABLE_NAME, COUNT(*) FROM ALL_TABLES GROUP BY TABLE_NAME", + "join": "SELECT A.TABLE_NAME FROM ALL_TABLES A JOIN ALL_TABLES B ON A.TABLE_NAME = B.TABLE_NAME WHERE A.TABLE_NAME LIKE 'DBX%'", + "subquery": "SELECT TABLE_NAME FROM ALL_TABLES WHERE TABLE_NAME IN (SELECT TABLE_NAME FROM ALL_TABLES WHERE TABLE_NAME LIKE 'DBX%')", + "cte": "WITH Q AS (SELECT TABLE_NAME FROM ALL_TABLES) SELECT * FROM Q LIMIT 10", + "complex_cte": "WITH Q AS (SELECT TABLE_NAME FROM ALL_TABLES) SELECT A.TABLE_NAME, COUNT(*) FROM Q A JOIN ALL_TABLES B ON A.TABLE_NAME = B.TABLE_NAME JOIN ALL_TABLES C ON A.TABLE_NAME = C.TABLE_NAME WHERE A.TABLE_NAME LIKE 'DBX%' GROUP BY A.TABLE_NAME ORDER BY A.TABLE_NAME LIMIT 10", + "union": "SELECT TABLE_NAME FROM ALL_TABLES UNION ALL SELECT TABLE_NAME FROM ALL_TABLES", + } { + t.Run(name, func(t *testing.T) { + result, err := s.executeQuery(queryOptions{SQL: "EXPLAIN VERBOSE " + sql, Database: params.Database, Schema: schema, MaxRows: 100, TimeoutSecs: 30}) + if err != nil { + t.Fatalf("explain query: %v", err) + } + if len(result.Columns) != 1 || !strings.EqualFold(result.Columns[0], "plan_path") { + t.Fatalf("unexpected columns: %#v", result.Columns) + } + if len(result.Rows) == 0 || len(result.Rows[0]) == 0 || result.Rows[0][0] == nil || strings.TrimSpace(fmt.Sprint(result.Rows[0][0])) == "" { + t.Fatal("empty explain plan") + } + plan := fmt.Sprint(result.Rows[0][0]) + t.Logf("native plan:\n%s", plan) + if !strings.Contains(plan, "Scan") && !strings.Contains(plan, "Join") && !strings.Contains(plan, "Group") { + t.Fatalf("no operator in plan: %s", plan) + } + }) + } + if err := s.validateConnection(); err != nil { + t.Fatalf("session not reusable after EXPLAIN: %v", err) + } +} diff --git a/apps/desktop/src/components/explain/ExplainPlanDiagram.vue b/apps/desktop/src/components/explain/ExplainPlanDiagram.vue index 87e47c8a83..690e43dec9 100644 --- a/apps/desktop/src/components/explain/ExplainPlanDiagram.vue +++ b/apps/desktop/src/components/explain/ExplainPlanDiagram.vue @@ -75,6 +75,7 @@ const MAX_ZOOM = 1.6; const FIT_ZOOM = 1.3; const layout = computed(() => buildPlanCanvas(props.nodes)); +const hasKnownCostModel = computed(() => layout.value.nodes.some((item) => item.node.costModel !== "unknown")); const viewport = ref(); const zoom = ref(1); const selectedIndex = ref(-1); @@ -269,10 +270,12 @@ watch(
- {{ t("explain.legendHeat") }} - < 5% - 5–20% - > 20% + {{ t("explain.legendEdge") }}
@@ -295,7 +298,7 @@ watch(
-
+
{{ t("explain.costShare") }}
{{ costPercent(selected.costShare) || "—" }}
diff --git a/apps/desktop/src/components/explain/__tests__/ExplainPlanViewer.xugu.spec.ts b/apps/desktop/src/components/explain/__tests__/ExplainPlanViewer.xugu.spec.ts new file mode 100644 index 0000000000..d5fe540115 --- /dev/null +++ b/apps/desktop/src/components/explain/__tests__/ExplainPlanViewer.xugu.spec.ts @@ -0,0 +1,53 @@ +// @vitest-environment happy-dom +import { afterEach, describe, expect, it } from "vitest"; +import { createApp, nextTick, type App } from "vue"; +import { createI18n } from "vue-i18n"; +import en from "@/i18n/locales/en"; +import { parseXuguExplainText } from "@/lib/diagram/xuguExplainPlan"; +import ExplainPlanViewer from "@/components/explain/ExplainPlanViewer.vue"; + +let app: App | undefined; +afterEach(() => { + app?.unmount(); + app = undefined; + document.body.innerHTML = ""; +}); + +describe("Xugu explain viewer", () => { + it.each(["canvas", "tree", "summary", "raw"] as const)("keeps CTE names visible in the %s view", async (view) => { + const plan = parseXuguExplainText("With Query(Q)\n1 VTScan\nMain Query\n1 WithRef[(1 1)](WithQry=Q)"); + const container = document.createElement("div"); + document.body.append(container); + app = createApp(ExplainPlanViewer, { plan, defaultView: view }); + app.use(createI18n({ legacy: false, locale: "en", messages: { en } })); + app.mount(container); + await nextTick(); + expect(container.textContent).toContain("With Query(Q)"); + expect(container.textContent).toContain("Main Query"); + }); + + it.each(["canvas", "tree", "summary", "raw"] as const)("reuses the %s view without measured statistics or fake shares", async (view) => { + const text = "1 SeqScan[(1 1) cost=0,result_num=12](table=ORDERS)\n-----------------------Tips--------------------------\n1 scan_filter: ID > 1"; + const plan = parseXuguExplainText(text); + const container = document.createElement("div"); + document.body.append(container); + app = createApp(ExplainPlanViewer, { plan, defaultView: view }); + app.use(createI18n({ legacy: false, locale: "en", messages: { en } })); + app.mount(container); + await nextTick(); + expect(container.textContent).toContain("XUGU"); + expect(container.textContent).toContain("TEXT"); + expect(container.textContent).not.toContain("JSON"); + expect(container.textContent).not.toContain("ANALYZE"); + expect(container.textContent).not.toContain("A-TRACE"); + expect(container.textContent).not.toContain("µs"); + expect(container.textContent).not.toContain(en.explain.legendHeat); + expect(container.textContent).not.toContain(en.explain.costShare); + if (view === "raw") expect(container.textContent).toContain(text); + else expect(container.textContent).toContain("ORDERS"); + if (view === "tree" || view === "canvas") { + expect(container.textContent).toContain("scan_filter"); + expect(container.textContent).toContain("ID > 1"); + } + }); +}); diff --git a/apps/desktop/src/lib/__tests__/database/databaseDriverManifest.spec.ts b/apps/desktop/src/lib/__tests__/database/databaseDriverManifest.spec.ts index 006d584ebf..b898aa0cd6 100644 --- a/apps/desktop/src/lib/__tests__/database/databaseDriverManifest.spec.ts +++ b/apps/desktop/src/lib/__tests__/database/databaseDriverManifest.spec.ts @@ -17,14 +17,13 @@ describe("databaseDriverManifest", () => { sqlFileExecution: true, databaseCreate: false, fieldLineage: false, - sqlExplain: false, + sqlExplain: true, userAdmin: true, driverManagement: true, }); - for (const capability of ["objectSource", "tableDataEdit", "userAdmin"] as const) { + for (const capability of ["objectSource", "tableDataEdit", "userAdmin", "sqlExplain"] as const) { expect(supportsDatabaseFeature("xugu", capability), capability).toBe(true); } - expect(supportsDatabaseFeature("xugu", "sqlExplain")).toBe(false); }); it("uses agent cursor only for agent or external runtimes", () => { diff --git a/apps/desktop/src/lib/__tests__/query/xuguExplainPlan.spec.ts b/apps/desktop/src/lib/__tests__/query/xuguExplainPlan.spec.ts new file mode 100644 index 0000000000..827c23791f --- /dev/null +++ b/apps/desktop/src/lib/__tests__/query/xuguExplainPlan.spec.ts @@ -0,0 +1,160 @@ +import { describe, expect, it } from "vitest"; +import { flattenExplainPlanNodes, parseExplainResult, supportsExplainPlan } from "@/lib/diagram/explainPlan"; +import { parseXuguExplainText } from "@/lib/diagram/xuguExplainPlan"; +import { buildPlanCanvas, categorizePlanNode } from "@/lib/diagram/planCanvas"; +import type { QueryResult } from "@/types/database"; + +const PLAN = `1 LimitScan[(9 1) cost=0,result_num=1] +2 Sort[(7 1) cost=0,result_num=1] +3 HashGroup[(5 1) cost=0,result_num=1] +4 IndexJoin[(4 1) cost=210,result_num=2] +5 BtIdxScan[(2 1) cost=300,result_num=1](table=TAB_HINT_1)(index=IDX_HINT) +6 SeqScan[(1 2) cost=0,result_num=1](table=TAB_HINT_2) +-----------------------Tips-------------------------- +4 join_filter: (TAB_HINT_1.ID)=(TAB_HINT_2.ID) +5 scan_filter: (TAB_HINT_1.ID)=(3) +6 scan_filter: (TAB_HINT_2.ID)=(3)`; + +function result(rows: unknown[][], columns = ["plan_path"]): QueryResult { + return { columns, rows, affected_rows: 0, execution_time_ms: 1 }; +} + +describe("Xugu estimated explain plan", () => { + it("is enabled by the Xugu capability only, without enabling unrelated engines", () => { + expect(supportsExplainPlan("xugu")).toBe(true); + for (const type of ["mysql", "postgres", "dameng", "questdb", "doris", "oracle", "oceanbase-oracle", "sqlserver"] as const) expect(supportsExplainPlan(type), type).toBe(true); + expect(supportsExplainPlan("redis")).toBe(false); + expect(supportsExplainPlan(undefined)).toBe(false); + }); + + it.each(["cell", "rows"])("parses the %s transport without JSON decoding", (transport) => { + const parsed = parseExplainResult("xugu", result(transport === "cell" ? [[PLAN]] : PLAN.split("\n").map((line) => [line]))); + expect(parsed.raw).toBe(PLAN); + expect(parsed.databaseType).toBe("xugu"); + const flat = flattenExplainPlanNodes(parsed.nodes); + expect(flat.map((node) => node.nodeType)).toEqual(["LimitScan", "Sort", "HashGroup", "IndexJoin", "BtIdxScan", "SeqScan"]); + expect(parsed.nodes).toHaveLength(1); + const join = flat[3]; + expect(join.children.map((node) => node.id)).toEqual(["xugu-5", "xugu-6"]); + expect(join.details).toContain("join_filter: (TAB_HINT_1.ID)=(TAB_HINT_2.ID)"); + expect(flat[4]).toMatchObject({ relation: "TAB_HINT_1", index: "IDX_HINT", cost: "300", rows: "1" }); + expect(flat[4].details).toContain("scan_filter: (TAB_HINT_1.ID)=(3)"); + expect(flat[5].cost).toBe("0"); + expect(flat.some((node) => node.details.some((detail) => detail.startsWith("Actual Rows:")))).toBe(false); + }); + + it("accepts the live DUAL plan with no metrics", () => { + const [node] = parseExplainResult("xugu", result([["1 VTScan\n\n"]])).nodes; + expect(node.nodeType).toBe("VTScan"); + expect(node.cost).toBeUndefined(); + expect(node.rows).toBeUndefined(); + expect(node.estimatedTimeUs).toBeUndefined(); + }); + + it("parses a live catalog plan and preserves wrapped predicates", () => { + const raw = `1 Sort[(3 1) cost=304,result_num=3]\r\n2 BtIdxScan[(1 1) cost=300,result_num=3](table=SYS_TABLES)(index=TAB_IDX1)\r\n-----------------------Tips--------------------------\r\n2 scan_filter: (TABLE_NAME)LIKE('TEST%')\r\n AND CHECK_AUTH(TABLE_ID)\r\n`; + const parsed = parseXuguExplainText(raw); + expect(parsed.raw).toBe(raw); + expect(parsed.nodes[0].children[0].details).toContain("scan_filter: (TABLE_NAME)LIKE('TEST%')\nAND CHECK_AUTH(TABLE_ID)"); + expect(parsed.nodes[0].cost).toBe("304"); + }); + + it("finds plan_path case insensitively and ignores NULL cells", () => { + expect( + parseExplainResult( + "xugu", + result( + [ + [null, "1 VTScan"], + [42, null], + ], + ["other", "PLAN_PATH"], + ), + ).nodes[0].nodeType, + ).toBe("VTScan"); + }); + + it("preserves quoted identifiers and decimal/scientific estimates", () => { + const [node] = parseXuguExplainText('1 BtIdxScan[(1 1) cost=1.25e+3,result_num=0](table="模式"."订单(历史)")(index="idx""quoted")').nodes; + expect(node).toMatchObject({ relation: '"模式"."订单(历史)"', index: '"idx""quoted"', cost: "1.25e+3", rows: "0" }); + }); + + it("uses indentation rather than printed or execution numbers", () => { + const parsed = parseXuguExplainText("9 IndexJoin[(1 2) cost=1,result_num=1]\n10 SeqScan[(99 1)]\n11 FutureScan[(3 2)]\n12 VTScan"); + expect(parsed.nodes.map((node) => node.id)).toEqual(["xugu-9", "xugu-12"]); + expect(parsed.nodes[0].children.map((node) => node.id)).toEqual(["xugu-10", "xugu-11"]); + expect(categorizePlanNode(parsed.nodes[0].children[1].nodeType)).toBe("other"); + }); + + it("preserves live CTE sections, restarted IDs and section-local Tips", () => { + const raw = `With Query(Q) +1 HashJoin[(4 1) cost=3900,result_num=1600] +2 SeqScan[(3 1) cost=1000,result_num=500](table=SYS_OBJECTS) +3 BtIdxScan[(1 2) cost=300,result_num=320](table=SYS_TABLES)(index=TAB_IDX2) +-----------------------Tips-------------------------- +1 join_filter: CTE_PREDICATE + +Main Query +1 LimitScan[(25 1) cost=37,result_num=10] +2 Sort[(23 1) cost=152,result_num=41] +3 HashGroup[(21 1) cost=0,result_num=41] +4 HashJoin[(20 1) cost=8160,result_num=41] +5 HashJoin[(19 1) cost=6224,result_num=256] +6 WithRef[(18 1) cost=1600,result_num=1600](WithQry=Q) +7 SubQuery[(17 2) cost=1344,result_num=16] +8 IndexJoin[(16 1) cost=972,result_num=16] +9 BtIdxScan[(14 1) cost=1000,result_num=500](table=SYS_OBJECTS)(index=OBJ_IDX2) +10 BtIdxScan[(12 2) cost=300,result_num=3](table=SYS_TABLES)(index=TAB_IDX2) +11 SubQuery[(11 2) cost=1344,result_num=16] +12 IndexJoin[(10 1) cost=972,result_num=16] +13 BtIdxScan[(8 1) cost=1000,result_num=500](table=SYS_OBJECTS)(index=OBJ_IDX2) +14 BtIdxScan[(6 2) cost=300,result_num=3](table=SYS_TABLES)(index=TAB_IDX2) +-----------------------Tips-------------------------- +4 join_filter: MAIN_PREDICATE`; + const plan = parseXuguExplainText(raw); + expect(plan.nodes.map((node) => node.title)).toEqual(["With Query(Q)", "Main Query"]); + expect(plan.nodes[0].children[0].details).toContain("join_filter: CTE_PREDICATE"); + const flat = flattenExplainPlanNodes(plan.nodes); + expect(flat).toHaveLength(19); + expect(new Set(flat.map((node) => node.id)).size).toBe(19); + expect(flat.find((node) => node.id === "xugu-2-4")?.details).toContain("join_filter: MAIN_PREDICATE"); + expect(flat.find((node) => node.id === "xugu-2-8")?.children.map((node) => node.id)).toEqual(["xugu-2-9", "xugu-2-10"]); + expect(flat.find((node) => node.id === "xugu-2-4")?.children.map((node) => node.id)).toEqual(["xugu-2-5", "xugu-2-11"]); + expect(plan.raw).toBe(raw); + }); + + it("preserves multiword operators and rejects heading-only plans", () => { + expect(parseXuguExplainText("1 Union All[(11 1) cost=15800,result_num=3200]\n2 SubQuery[(5 1)]").nodes[0].nodeType).toBe("Union All"); + expect(() => parseXuguExplainText("With Query(Q)\nMain Query")).toThrow("no plan nodes"); + }); + + it("maps Xugu operators and keeps unknown operators visible", () => { + const categories = buildPlanCanvas(parseXuguExplainText(PLAN).nodes).nodes.map((node) => node.category); + expect(categories).toEqual(["result", "sort", "agg", "join", "iscan", "tscan"]); + for (const operator of ["SeqScan", "VTScan", "BtIdxScan", "BitmapScan", "HashJoin", "HashGroup"]) { + expect(categorizePlanNode(operator, "xugu"), operator).not.toBe("other"); + expect(categorizePlanNode(operator, "postgres"), operator).toBe("other"); + expect(categorizePlanNode(operator, "mysql"), operator).toBe("other"); + } + }); + + it("does not invent cumulative-cost shares or actual stats for Xugu", () => { + const canvas = buildPlanCanvas(parseXuguExplainText(PLAN).nodes); + expect(canvas.edges).toHaveLength(5); + expect(canvas.nodes.every((node) => node.costShare === undefined && node.actualRows === undefined)).toBe(true); + expect(canvas.nodes[4].node.cost).toBe("300"); + expect(canvas.nodes[4].rows).toBe(1); + const [postgres] = buildPlanCanvas([{ id: "pg", title: "Seq Scan", nodeType: "Seq Scan", cost: "300", children: [], details: [] }]).nodes; + expect(postgres.costShare).toBe(1); + }); + + it.each(["", "\n\r\n", "not an execution plan", "1 VTScan\n1 SeqScan"])("rejects empty or malformed plans: %j", (text) => { + expect(() => parseXuguExplainText(text)).toThrow(); + }); + + it("surfaces explicit query errors rather than drawing a successful empty plan", () => { + expect(() => parseExplainResult("xugu", { ...result([["[E1007] permission denied"]], ["Error"]), execution_error: true })).toThrow("[E1007] permission denied"); + expect(() => parseExplainResult("xugu", result([["data"]], ["other"]))).toThrow("plan_path"); + expect(() => parseExplainResult("xugu", result([]))).toThrow("no plan nodes"); + }); +}); diff --git a/apps/desktop/src/lib/diagram/explainPlan.ts b/apps/desktop/src/lib/diagram/explainPlan.ts index 4599b25596..fd258cbca7 100644 --- a/apps/desktop/src/lib/diagram/explainPlan.ts +++ b/apps/desktop/src/lib/diagram/explainPlan.ts @@ -2,14 +2,19 @@ import type { DatabaseType, QueryResult } from "@/types/database"; import * as api from "@/lib/backend/api"; import { supportsDatabaseFeature } from "@/lib/database/databaseDriverManifest"; import { isQueryExecutionErrorResult } from "@/lib/query/queryResultError"; +import { parseXuguExplainResult } from "./xuguExplainPlan"; export interface ExplainPlanNode { id: string; title: string; nodeType: string; + /** Optional dialect hint for engine-specific operator presentation. */ + dialect?: ExplainPlanDatabaseType; relation?: string; index?: string; cost?: string; + /** Suppress derived cost shares when the engine's cost accumulation is undocumented. */ + costModel?: "unknown"; rows?: string; width?: string; estimatedTimeUs?: string; @@ -17,7 +22,7 @@ export interface ExplainPlanNode { children: ExplainPlanNode[]; } -export type ExplainPlanDatabaseType = "mysql" | "postgres" | "dameng" | "questdb" | "doris" | "oracle" | "oceanbase-oracle" | "sqlserver"; +export type ExplainPlanDatabaseType = "mysql" | "postgres" | "dameng" | "questdb" | "doris" | "oracle" | "oceanbase-oracle" | "sqlserver" | "xugu"; export interface ParsedExplainPlan { databaseType: ExplainPlanDatabaseType; @@ -32,7 +37,7 @@ export function formatExplainPlanDetails(node: ExplainPlanNode | undefined, esti return node.estimatedTimeUs === undefined ? node.details : [`${estimatedTimeLabel}: ${node.estimatedTimeUs} µs`, ...node.details]; } -const SUPPORTED_EXPLAIN_TYPES = new Set(["mysql", "postgres", "dameng", "questdb", "doris", "oracle", "oceanbase-oracle", "sqlserver"]); +const SUPPORTED_EXPLAIN_TYPES = new Set(["mysql", "postgres", "dameng", "questdb", "doris", "oracle", "oceanbase-oracle", "sqlserver", "xugu"]); export function supportsExplainPlan(databaseType?: DatabaseType): databaseType is ExplainPlanDatabaseType { return !!databaseType && supportsDatabaseFeature(databaseType, "sqlExplain") && SUPPORTED_EXPLAIN_TYPES.has(databaseType); } @@ -43,7 +48,9 @@ export function buildExplainSql(databaseType: DatabaseType | undefined, sql: str } export function parseExplainResult(databaseType: ExplainPlanDatabaseType, result: QueryResult): ParsedExplainPlan { - if (databaseType === "dameng") { + if (databaseType === "xugu") { + return parseXuguExplainResult(result); + } else if (databaseType === "dameng") { return parseDamengExplain(result); } else if (databaseType === "questdb") { return parseQuestdbExplain(result); diff --git a/apps/desktop/src/lib/diagram/planCanvas.ts b/apps/desktop/src/lib/diagram/planCanvas.ts index 1303b353e1..e8f7ec377d 100644 --- a/apps/desktop/src/lib/diagram/planCanvas.ts +++ b/apps/desktop/src/lib/diagram/planCanvas.ts @@ -1,4 +1,4 @@ -import type { ExplainPlanNode } from "./explainPlan"; +import type { ExplainPlanDatabaseType, ExplainPlanNode } from "./explainPlan"; export type PlanCanvasCategory = "result" | "sort" | "join" | "tscan" | "iscan" | "lookup" | "mat" | "agg" | "xchg" | "mod" | "other"; @@ -13,6 +13,13 @@ export const PLAN_CANVAS_PAD = 36; * while a bare "Merge" is DML, "Clustered Index Scan" reads a whole table while * "Index Scan" does not, and "SORT AGGREGATE" is an aggregate, not a sort. */ +const XUGU_CATEGORY_RULES: Array<[RegExp, PlanCanvasCategory]> = [ + [/^(?:seqscan|vtscan)$/, "tscan"], + [/^(?:btidxscan|bitmapscan)$/, "iscan"], + [/^(?:indexjoin|hashjoin|mergejoin|nestloop)$/, "join"], + [/^(?:hashgroup|sortgroup)$/, "agg"], +]; + const CATEGORY_RULES: Array<[RegExp, PlanCanvasCategory]> = [ // MySQL access types are single ambiguous words, so they only match exactly. [/^(?:eq_ref|const|system)$/, "lookup"], @@ -31,9 +38,14 @@ const CATEGORY_RULES: Array<[RegExp, PlanCanvasCategory]> = [ [/result|^select\b|select statement|limit|query_block|nset\d*|prjt\d*|union|\btop\b/, "result"], ]; -export function categorizePlanNode(nodeType: string): PlanCanvasCategory { +export function categorizePlanNode(nodeType: string, dialect?: ExplainPlanDatabaseType): PlanCanvasCategory { const normalized = nodeType.trim().toLowerCase(); if (!normalized) return "other"; + if (dialect === "xugu") { + for (const [pattern, category] of XUGU_CATEGORY_RULES) { + if (pattern.test(normalized)) return category; + } + } for (const [pattern, category] of CATEGORY_RULES) { if (pattern.test(normalized)) return category; } @@ -105,7 +117,7 @@ export function buildPlanCanvas(roots: ExplainPlanNode[]): PlanCanvasLayout { function place(node: ExplainPlanNode, depth: number, parent?: PlanCanvasNode): PlanCanvasNode { const placed: PlanCanvasNode = { node, - category: categorizePlanNode(node.nodeType), + category: categorizePlanNode(node.nodeType, node.dialect), x: PLAN_CANVAS_PAD + depth * (PLAN_CANVAS_NODE_W + PLAN_CANVAS_GAP_X), y: 0, rows: parsePlanNumber(node.rows), @@ -123,7 +135,7 @@ export function buildPlanCanvas(roots: ExplainPlanNode[]): PlanCanvasLayout { } const cost = parsePlanNumber(node.cost); - if (cost !== undefined) { + if (cost !== undefined && node.costModel !== "unknown") { // Costs are cumulative over the subtree in PG / SQL Server / Oracle. const childCost = node.children.reduce((total, child) => total + (parsePlanNumber(child.cost) ?? 0), 0); selfCosts.set(placed, Math.max(0, cost - childCost)); diff --git a/apps/desktop/src/lib/diagram/xuguExplainPlan.ts b/apps/desktop/src/lib/diagram/xuguExplainPlan.ts new file mode 100644 index 0000000000..f45b4394b5 --- /dev/null +++ b/apps/desktop/src/lib/diagram/xuguExplainPlan.ts @@ -0,0 +1,108 @@ +import type { QueryResult } from "@/types/database"; +import type { ExplainPlanNode, ParsedExplainPlan } from "./explainPlan"; +import { isQueryExecutionErrorResult } from "@/lib/query/queryResultError"; + +/** Xugu EXPLAIN VERBOSE returns plan_path text, as one multiline cell or rows. */ +export function parseXuguExplainResult(result: QueryResult): ParsedExplainPlan { + if (isQueryExecutionErrorResult(result)) { + throw new Error(String(result.rows[0]?.[0] ?? "XuguDB EXPLAIN failed")); + } + const columnIndex = result.columns.findIndex((column) => column.trim().toLowerCase() === "plan_path"); + if (columnIndex < 0) throw new Error("XuguDB EXPLAIN did not return plan_path"); + const raw = result.rows + .map((row) => row[columnIndex]) + .filter((value) => value !== null && value !== undefined) + .map(String) + .join("\n"); + return parseXuguExplainText(raw); +} + +export function parseXuguExplainText(raw: string): ParsedExplainPlan { + const nodes: ExplainPlanNode[] = []; + const stack: Array<{ indent: number; node: ExplainPlanNode }> = []; + const byLine = new Map(); + let inTips = false; + let lastTipNode: ExplainPlanNode | undefined; + let section: ExplainPlanNode | undefined; + let sectionNumber = 0; + + for (const line of raw.replace(/\r\n?/g, "\n").split("\n")) { + if (!line.trim()) continue; + // CTE plans contain independent numbered plans; numbering restarts in each + // With Query(...) / Main Query section, including after a Tips block. + const heading = line.trim(); + if (/^With Query\(.+\)$/i.test(heading) || /^Main Query$/i.test(heading)) { + sectionNumber += 1; + section = { id: `xugu-section-${sectionNumber}`, title: heading, nodeType: heading, dialect: "xugu", costModel: "unknown", details: [], children: [] }; + nodes.push(section); + stack.length = 0; + byLine.clear(); + inTips = false; + lastTipNode = undefined; + continue; + } + if (/^-+\s*Tips\s*-+$/i.test(line.trim())) { + inTips = true; + continue; + } + if (inTips) { + const tip = line.match(/^\s*(\d+)\s+(.+)$/); + if (tip) { + lastTipNode = byLine.get(tip[1]); + lastTipNode?.details.push(tip[2].trim()); + } else if (lastTipNode) { + // Long predicates may wrap onto unnumbered continuation lines. + lastTipNode.details[lastTipNode.details.length - 1] += `\n${line.trim()}`; + } + continue; + } + + // The printed number identifies a plan line (and its Tips), not a depth. + // Execution step/branch numbers inside [(...)] are not hierarchy either. + const match = line.match(/^(\s*)(\d+)([ \t]+)([A-Za-z][A-Za-z0-9_]*(?:[ \t]+[A-Za-z][A-Za-z0-9_]*)*)(.*)$/); + if (!match) throw new Error(`Unrecognized XuguDB plan line: ${line.trim()}`); + const [, prefix, lineId, spacing, operator, suffix] = match; + if (byLine.has(lineId)) throw new Error(`Duplicate XuguDB plan line: ${lineId}`); + // Native output compensates spaces when line IDs grow from 9 to 10. + // Compare the operator's column, not just the whitespace after the ID. + const indent = (prefix + lineId + spacing).replace(/\t/g, " ").length; + const relation = planAttribute(suffix, "table"); + const index = planAttribute(suffix, "index"); + const cost = numericAttribute(suffix, "cost"); + const rows = numericAttribute(suffix, "result_num"); + const node: ExplainPlanNode = { + id: section ? `xugu-${sectionNumber}-${lineId}` : `xugu-${lineId}`, + title: relation ? `${operator} on ${relation}` : operator, + nodeType: operator, + dialect: "xugu", + relation, + index, + cost, + costModel: "unknown", + rows, + // Preserve native step/branch and unrecognized attributes without inventing stats. + details: suffix.trim() ? [suffix.trim()] : [], + children: [], + }; + while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop(); + const parent = stack[stack.length - 1]?.node; + if (parent) parent.children.push(node); + else if (section) section.children.push(node); + else nodes.push(node); + stack.push({ indent, node }); + byLine.set(lineId, node); + } + + if (!nodes.length || nodes.every((node) => node.id.startsWith("xugu-section-") && !node.children.length)) throw new Error("XuguDB EXPLAIN returned no plan nodes"); + return { databaseType: "xugu", raw, nodes }; +} + +function numericAttribute(source: string, name: string): string | undefined { + return source.match(new RegExp(`\\b${name}\\s*=\\s*(\\d+(?:\\.\\d+)?(?:[eE][+-]?\\d+)?)(?=\\s*[,\\]\\)])`, "i"))?.[1]; +} + +function planAttribute(source: string, name: string): string | undefined { + // Quoted identifiers may contain parentheses; do not stop inside a quote. + const match = source.match(new RegExp(`\\(${name}\\s*=\\s*((?:"(?:""|[^"])*"|'(?:''|[^'])*'|[^)])*)\\)`, "i")); + return match?.[1].trim() || undefined; +} diff --git a/apps/desktop/src/stores/__tests__/queryStore.xuguExplain.spec.ts b/apps/desktop/src/stores/__tests__/queryStore.xuguExplain.spec.ts new file mode 100644 index 0000000000..9b9c7adcd8 --- /dev/null +++ b/apps/desktop/src/stores/__tests__/queryStore.xuguExplain.spec.ts @@ -0,0 +1,85 @@ +import { createPinia, setActivePinia } from "pinia"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { QueryResult } from "@/types/database"; + +const mocks = vi.hoisted(() => ({ buildExplainSql: vi.fn(), executeQuery: vi.fn(), closeClientSession: vi.fn(), saveOpenTabsState: vi.fn(), getConfig: vi.fn(), getExplainInfo: vi.fn() })); +vi.mock("@/lib/diagram/explainPlan", async (importOriginal) => ({ ...(await importOriginal()), buildExplainSql: mocks.buildExplainSql })); +vi.mock("@/lib/backend/api", () => ({ executeQuery: mocks.executeQuery, closeClientConnectionSession: mocks.closeClientSession, saveOpenTabsState: mocks.saveOpenTabsState, getExplainInfo: mocks.getExplainInfo })); +vi.mock("@/stores/connectionStore", () => ({ useConnectionStore: () => ({ getConfig: mocks.getConfig, recordConnectionLostError: vi.fn() }) })); +vi.mock("@/stores/settingsStore", () => ({ useSettingsStore: () => ({ editorSettings: { pageSize: 100, openTabsRestoreMode: "all", confirmUnsavedSqlClose: false } }) })); + +const SQL = "SELECT * FROM ORDERS WHERE ID = 1"; +const EXPLAIN = `EXPLAIN VERBOSE ${SQL}`; +const PLAN: QueryResult = { columns: ["plan_path"], rows: [["1 SeqScan[(1 1) cost=0,result_num=1](table=ORDERS)"]], affected_rows: 0, execution_time_ms: 1 }; + +describe("queryStore Xugu EXPLAIN", () => { + beforeEach(() => { + vi.clearAllMocks(); + vi.unstubAllGlobals(); + const data = new Map(); + vi.stubGlobal("localStorage", { getItem: (key: string) => data.get(key) ?? null, setItem: (key: string, value: string) => data.set(key, value), removeItem: (key: string) => data.delete(key) }); + setActivePinia(createPinia()); + mocks.getConfig.mockReturnValue({ id: "xugu-1", name: "Xugu", db_type: "xugu", query_timeout_secs: 30 }); + mocks.buildExplainSql.mockResolvedValue({ ok: true, sql: EXPLAIN }); + mocks.executeQuery.mockResolvedValue(PLAN); + mocks.closeClientSession.mockResolvedValue(undefined); + mocks.saveOpenTabsState.mockResolvedValue(undefined); + }); + + it("uses the scoped query path, real parser, timeout and existing session cleanup", async () => { + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", "SHOP_DEMO", "Query", "query", "APP_TEST"); + await store.explainTabSql(id, SQL, "xugu"); + expect(mocks.executeQuery).toHaveBeenCalledWith("xugu-1", "SHOP_DEMO", EXPLAIN, "APP_TEST", expect.any(String), expect.objectContaining({ clientSessionId: `${id}:explain`, timeoutSecs: 30 })); + expect(mocks.getExplainInfo).not.toHaveBeenCalled(); + expect(mocks.closeClientSession).toHaveBeenCalled(); + expect(store.tabs.find((tab) => tab.id === id)).toMatchObject({ isExplaining: false, explainError: undefined, explainSql: EXPLAIN, explainPlan: { databaseType: "xugu", nodes: [{ nodeType: "SeqScan", relation: "ORDERS", rows: "1" }] } }); + }); + + it("does not enable actual execution when an autotrace mode is accidentally requested", async () => { + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", "SYSTEM", "Query", "query", "SYSDBA"); + await store.explainTabSql(id, SQL, "xugu", "autotrace"); + expect(mocks.buildExplainSql).toHaveBeenCalledWith("xugu", SQL); + expect(mocks.executeQuery).toHaveBeenCalledWith("xugu-1", "SYSTEM", EXPLAIN, "SYSDBA", expect.any(String), expect.objectContaining({ executionMode: undefined })); + }); + + it.each(["SYSTEM", "SHOP_DEMO"])("preserves the selected %s database", async (database) => { + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", database, "Query", "query", "OWNER_B"); + await store.explainTabSql(id, SQL, "xugu"); + expect(mocks.executeQuery.mock.calls[0].slice(0, 4)).toEqual(["xugu-1", database, EXPLAIN, "OWNER_B"]); + }); + + it("does not send rejected SQL to the Agent", async () => { + mocks.buildExplainSql.mockResolvedValue({ ok: false, reason: "unsafe" }); + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", "SYSTEM", "Query", "query"); + expect(await store.explainTabSql(id, "DELETE FROM ORDERS", "xugu")).toEqual({ ok: false, reason: "unsafe" }); + expect(mocks.executeQuery).not.toHaveBeenCalled(); + expect(store.tabs[0]).toMatchObject({ isExplaining: false, explainError: "unsafe", explainPlan: undefined }); + }); + + it.each(["permission denied", "query timed out"])("surfaces %s and closes the explain session", async (message) => { + mocks.executeQuery.mockRejectedValue(new Error(message)); + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", "SHOP_DEMO", "Query", "query", "APP_TEST"); + await store.explainTabSql(id, SQL, "xugu"); + expect(store.tabs[0]).toMatchObject({ isExplaining: false, explainError: message, explainPlan: undefined }); + expect(mocks.closeClientSession).toHaveBeenCalled(); + }); + + it("does not turn an explicit execution-error result into a successful plan", async () => { + mocks.executeQuery.mockResolvedValue({ ...PLAN, columns: ["Error"], rows: [["[E5021] object not found"]], execution_error: true }); + const { useQueryStore } = await import("@/stores/queryStore"); + const store = useQueryStore(); + const id = store.createTab("xugu-1", "SYSTEM", "Query", "query"); + await store.explainTabSql(id, SQL, "xugu"); + expect(store.tabs[0]).toMatchObject({ isExplaining: false, explainError: "[E5021] object not found", explainPlan: undefined }); + }); +}); diff --git a/crates/dbx-core/assets/database-drivers.manifest.json b/crates/dbx-core/assets/database-drivers.manifest.json index c70fb5dc30..8c8575f33c 100644 --- a/crates/dbx-core/assets/database-drivers.manifest.json +++ b/crates/dbx-core/assets/database-drivers.manifest.json @@ -2537,7 +2537,7 @@ "sqlFileExecution": true, "databaseCreate": false, "fieldLineage": false, - "sqlExplain": false, + "sqlExplain": true, "userAdmin": true, "driverManagement": true } diff --git a/crates/dbx-sql-core/src/query_execution_sql.rs b/crates/dbx-sql-core/src/query_execution_sql.rs index 40fd4966fc..fbcab26d4f 100644 --- a/crates/dbx-sql-core/src/query_execution_sql.rs +++ b/crates/dbx-sql-core/src/query_execution_sql.rs @@ -83,6 +83,7 @@ enum EstimatedPlanSqlGeneration { Postgres, Mysql, Plain, + Xugu, Oracle, SqlServer, Json, @@ -129,6 +130,14 @@ pub fn build_explain_sql(options: ExplainSqlOptions) -> ExplainSqlBuildResult { if !is_safe_explain_sql_for_database(&source, options.database_type) { return explain_err("unsafe"); } + if options.database_type == Some(DatabaseType::Xugu) { + // Xugu's documented SELECT forms; do not inherit PG-only TABLE/VALUES + // shortcuts or permit DML/Autotrace in the first visual-plan implementation. + let leading = strip_sql_comments(&source).trim_start().to_lowercase(); + if !["select", "with"].iter().any(|keyword| starts_with_explain_keyword_boundary(&leading, keyword)) { + return explain_err("unsafe"); + } + } if options.analyze == Some(true) && options.database_type.is_some_and(|database_type| { matches!(database_type, DatabaseType::Postgres | DatabaseType::SqlServer) @@ -149,6 +158,7 @@ pub fn build_explain_sql(options: ExplainSqlOptions) -> ExplainSqlBuildResult { } EstimatedPlanSqlGeneration::Postgres => format!("EXPLAIN (FORMAT JSON) {source}"), EstimatedPlanSqlGeneration::Plain => format!("EXPLAIN {source}"), + EstimatedPlanSqlGeneration::Xugu => format!("EXPLAIN VERBOSE {source}"), EstimatedPlanSqlGeneration::Oracle => format!("EXPLAIN PLAN FOR {source}"), // STATISTICS XML returns the same ShowPlanXML document plus per-operator // runtime counters, at the price of actually running the statement. @@ -192,11 +202,12 @@ pub fn build_dropped_file_preview_sql(options: DroppedFilePreviewSqlOptions) -> pub fn estimated_plan_strategy(database_type: Option) -> Option { use EstimatedPlanAcquisition::{DriverNative, GeneratedSql, SqlServerShowPlanSession}; use EstimatedPlanFormat::{Json, Text, Xml}; - use EstimatedPlanSqlGeneration::{Mysql, Oracle, Plain, Postgres, SqlServer}; + use EstimatedPlanSqlGeneration::{Mysql, Oracle, Plain, Postgres, SqlServer, Xugu}; let strategy = match database_type? { DatabaseType::Mysql => EstimatedPlanStrategy { sql_generation: Mysql, acquisition: GeneratedSql, format: Json }, DatabaseType::Doris => EstimatedPlanStrategy { sql_generation: Plain, acquisition: GeneratedSql, format: Text }, + DatabaseType::Xugu => EstimatedPlanStrategy { sql_generation: Xugu, acquisition: GeneratedSql, format: Text }, DatabaseType::Postgres => { EstimatedPlanStrategy { sql_generation: Postgres, acquisition: GeneratedSql, format: Json } } @@ -1514,6 +1525,59 @@ mod tests { assert!(!is_oracle_proven_read_only_statement("SELECT 1 UNION SELECT 2")); } + #[test] + fn builds_xugu_verbose_text_explain_without_executing_the_query() { + for sql in [ + "SELECT * FROM \"APP_TEST\".\"ORDERS\" WHERE id = 1", + "WITH q AS (SELECT 1 FROM DUAL) SELECT * FROM q", + "/* plan */ SELECT 1 FROM DUAL", + "SELECT 'DELETE; DROP TABLE x' FROM DUAL", + ] { + for analyze in [None, Some(false), Some(true)] { + let result = build_explain_sql(ExplainSqlOptions { + database_type: Some(DatabaseType::Xugu), + format: Some(ExplainFormat::Json), + analyze, + sql: format!(" {sql}; "), + }); + assert_eq!(result.sql.as_deref(), Some(format!("EXPLAIN VERBOSE {sql}").as_str())); + assert!(result.ok); + } + } + assert_eq!(estimated_plan_format(Some(DatabaseType::Xugu)), EstimatedPlanFormat::Text); + assert_eq!( + estimated_plan_strategy(Some(DatabaseType::Xugu)).unwrap().acquisition(), + EstimatedPlanAcquisition::GeneratedSql + ); + } + + #[test] + fn xugu_explain_rejects_writes_multiple_statements_and_unsupported_forms() { + for sql in [ + "DELETE FROM t", + "UPDATE t SET a = 1", + "INSERT INTO t VALUES (1)", + "MERGE INTO t USING s ON t.id = s.id WHEN MATCHED THEN UPDATE SET t.a = 1", + "SELECT 1; DROP TABLE t", + "WITH q AS (DELETE FROM t RETURNING *) SELECT * FROM q", + "WITH FUNCTION f RETURN INT IS BEGIN RETURN 1; END; SELECT f() FROM DUAL", + "EXPLAIN SELECT 1", + "TABLE t", + "VALUES (1)", + "SELECTED", + "", + ] { + let result = build_explain_sql(ExplainSqlOptions { + database_type: Some(DatabaseType::Xugu), + format: None, + analyze: None, + sql: sql.to_string(), + }); + assert!(!result.ok, "unsafe Xugu explain source: {sql}"); + assert!(result.sql.is_none()); + } + } + #[test] fn builds_postgres_json_explain_sql() { let result = build_explain_sql(ExplainSqlOptions { @@ -1845,6 +1909,7 @@ mod tests { let cases = [ (DatabaseType::Mysql, "EXPLAIN FORMAT=JSON SELECT 1", Json, GeneratedSql), (DatabaseType::Doris, "EXPLAIN SELECT 1", Text, GeneratedSql), + (DatabaseType::Xugu, "EXPLAIN VERBOSE SELECT 1", Text, GeneratedSql), (DatabaseType::Postgres, "EXPLAIN (FORMAT JSON) SELECT 1", Json, GeneratedSql), (DatabaseType::Questdb, "EXPLAIN SELECT 1", Text, GeneratedSql), (DatabaseType::Dameng, "EXPLAIN SELECT 1", Text, DriverNative), diff --git a/docs/images/xugu-visual-explain.jpg b/docs/images/xugu-visual-explain.jpg new file mode 100644 index 0000000000..298c3afae9 Binary files /dev/null and b/docs/images/xugu-visual-explain.jpg differ diff --git a/plugins/connection-types/xugu.yaml b/plugins/connection-types/xugu.yaml index 18dedabebc..afbd16c46b 100644 --- a/plugins/connection-types/xugu.yaml +++ b/plugins/connection-types/xugu.yaml @@ -31,6 +31,6 @@ capabilities: sqlFileExecution: true databaseCreate: false fieldLineage: false - sqlExplain: false + sqlExplain: true userAdmin: true driverManagement: true