The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feature: Explain tab in SQL editor that shows output of explain analyze (#41569)
Ali Waseem89e0fe4f2870
diff --git a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.Header.tsx b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.Header.tsxindex d90a1305ac2..5aef13ebcf7 100644--- a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.Header.tsx+++ b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.Header.tsx@@ -1,5 +1,13 @@-import { Activity, ArrowUp, Clock, Database, GitMerge, Hash, Zap } from 'lucide-react'-import { Badge } from 'ui'+import { ArrowUp, Eye, Code } from 'lucide-react'++import { useFlag } from 'common'+import { AiIconAnimation, Button } from 'ui'+import { SIDEBAR_KEYS } from 'components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider'+import { useAiAssistantStateSnapshot } from 'state/ai-assistant-state'+import { useSqlEditorV2StateSnapshot } from 'state/sql-editor-v2'+import { useSidebarManagerSnapshot } from 'state/sidebar-manager-state'+import { buildExplainPrompt } from './ExplainVisualizer.ai'+import type { QueryPlanRow } from './ExplainVisualizer.types'export interface ExplainSummary {totalTime: number@@ -11,41 +19,83 @@ export interface ExplainHeaderProps {mode: 'visual' | 'raw'onToggleMode: () => voidsummary?: ExplainSummary+ id?: string+ rows?: readonly QueryPlanRow[]}-export function ExplainHeader({ mode, onToggleMode, summary }: ExplainHeaderProps) {+export function ExplainHeader({ mode, onToggleMode, summary, id, rows }: ExplainHeaderProps) {const isVisual = mode === 'visual'+ const snapV2 = useSqlEditorV2StateSnapshot()+ const { openSidebar } = useSidebarManagerSnapshot()+ const aiSnap = useAiAssistantStateSnapshot()++ const handleExplainWithAI = () => {+ if (!id) return+ const snippet = snapV2.snippets[id]?.snippet+ if (!snippet?.content?.sql) return++ const { query, prompt } = buildExplainPrompt({+ sql: snippet.content.sql,+ explainPlanRows: (rows as QueryPlanRow[]) ?? [],+ })++ openSidebar(SIDEBAR_KEYS.AI_ASSISTANT)+ aiSnap.newChat({+ sqlSnippets: [+ {+ label: 'Query',+ content: query,+ },+ ],+ initialMessage: prompt,+ })+ }+const hasSummaryStats =isVisual && summary && (summary.totalTime > 0 || (summary.hasSeqScan && !summary.hasIndexScan))return (<div className="bg-surface-100 border-b px-4 py-3 flex flex-col gap-3 text-xs">{/* Title row */}- <div className="flex items-center gap-2 text-sm">- <h3 className="font-medium text-foreground">Query Execution Plan</h3>- {/* Summary stats - only show in visual mode when we have the data */}- {hasSummaryStats && (- <div className="flex items-center gap-4 flex-wrap">- {summary.totalTime > 0 && (- <div className="flex items-center gap-1.5">- <span className="text-foreground-light">/</span>- <span className="text-foreground-light">Total time</span>- <span className="font-mono font-medium text-foreground">- {summary.totalTime.toFixed(2)}ms- </span>- </div>- )}- </div>- )}- <button- type="button"- onClick={onToggleMode}- className="font-mono text-xs text-foreground-lighter hover:text-foreground transition-colors"- aria-label={isVisual ? 'Switch to raw explain output' : 'Switch to visual explain output'}- >- {isVisual ? '[VISUAL]' : '[RAW]'}- </button>+ <div className="flex items-center justify-between text-sm">+ <div className="flex items-center gap-2">+ <h3 className="font-medium text-foreground">Query Execution Plan</h3>+ {/* Summary stats - only show in visual mode when we have the data */}+ {hasSummaryStats && (+ <div className="flex items-center gap-4 flex-wrap">+ {summary.totalTime > 0 && (+ <div className="flex items-center gap-1.5">+ <span className="text-foreground-light">/</span>+ <span className="text-foreground-light">Total time</span>+ <span className="font-mono font-medium text-foreground">+ {summary.totalTime.toFixed(2)}ms+ </span>+ </div>+ )}+ </div>+ )}+ </div>+ <div className="flex items-center gap-2">+ {id && rows && (+ <Button+ type="default"+ size="tiny"+ icon={<AiIconAnimation size={14} />}+ onClick={handleExplainWithAI}+ >+ Explain with AI+ </Button>+ )}+ <Button+ type="default"+ size="tiny"+ icon={isVisual ? <Code size={14} /> : <Eye size={14} />}+ onClick={onToggleMode}+ >+ {isVisual ? 'Raw' : 'Visual'}+ </Button>+ </div></div>{/* How to read */}diff --git a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.ai.ts b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.ai.tsnew file mode 100644index 00000000000..1258cb526b4--- /dev/null+++ b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.ai.ts@@ -0,0 +1,45 @@+import type { QueryPlanRow } from './ExplainVisualizer.types'++export interface ExplainPromptInput {+ sql: string+ explainPlanRows: QueryPlanRow[]+}++export interface ExplainPromptOutput {+ query: string+ prompt: string+}++export function buildExplainPrompt({+ sql,+ explainPlanRows,+}: ExplainPromptInput): ExplainPromptOutput {+ const explainPlan = explainPlanRows.map((row) => row['QUERY PLAN']).join('\n')++ const prompt = `Explain this PostgreSQL EXPLAIN ANALYZE output in simple terms:++\`\`\`sql+${sql}+\`\`\`++\`\`\`+${explainPlan}+\`\`\`++Format your response with:++**What it does** - 1-2 sentences.++**How it runs** - Briefly explain the plan from bottom to top in plain English. Mention key operations (scans, joins, sorts) and why PostgreSQL chose them.++**Issues** - Identify bottlenecks: slowest steps, sequential scans on large tables, inefficient joins, missing indexes. Be specific with timings from the plan.++**Fixes** - 2-3 specific suggestions with CREATE INDEX statements if applicable.++Keep it concise. Focus on actionable insights.`++ return {+ query: sql,+ prompt,+ }+}diff --git a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.tsx b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.tsxindex df339cd52dc..764e89a345b 100644--- a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.tsx+++ b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.tsx@@ -7,9 +7,10 @@ import type { QueryPlanRow } from './ExplainVisualizer.types'export interface ExplainVisualizerProps {rows: readonly QueryPlanRow[]onShowRaw?: () => void+ id?: string}-export function ExplainVisualizer({ rows, onShowRaw }: ExplainVisualizerProps) {+export function ExplainVisualizer({ rows, onShowRaw, id }: ExplainVisualizerProps) {const parsedTree = useMemo(() => createNodeTree(rows), [rows])const maxDuration = useMemo(() => calculateMaxDuration(parsedTree), [parsedTree])const summary = useMemo(() => calculateSummary(parsedTree), [parsedTree])@@ -26,7 +27,15 @@ export function ExplainVisualizer({ rows, onShowRaw }: ExplainVisualizerProps) {return (<div className="bg-studio border-t h-full flex flex-col min-h-0">- {onShowRaw && <ExplainHeader mode="visual" onToggleMode={onShowRaw} summary={summary} />}+ {onShowRaw && (+ <ExplainHeader+ mode="visual"+ onToggleMode={onShowRaw}+ summary={summary}+ id={id}+ rows={rows}+ />+ )}{/* Plan nodes */}<div className="flex-1 overflow-auto min-h-0">diff --git a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.utils.ts b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.utils.tsindex b44e2797a8b..5887d9c02b1 100644--- a/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.utils.ts+++ b/apps/studio/components/interfaces/ExplainVisualizer/ExplainVisualizer.utils.ts@@ -126,10 +126,15 @@ export function getOperationColor(operation: string): string {return 'text-foreground-light'}-export function isExplainQuery(rows: readonly any[]): boolean {- return (- rows.length > 0 && rows[0].hasOwnProperty('QUERY PLAN') && Object.keys(rows[0]).length === 1- )+export function isExplainQuery(rows: readonly unknown[]): boolean {+ if (rows.length === 0) return false+ const firstRow = rows[0]+ if (typeof firstRow !== 'object' || firstRow === null) return false+ return 'QUERY PLAN' in firstRow && Object.keys(firstRow).length === 1+}++export function isExplainSql(sql: string): boolean {+ return /^\s*explain\b/i.test(sql)}export function formatNodeDuration(ms: number | undefined): string {@@ -185,3 +190,35 @@ export function getScanBorderColor(operation: string): string {// Default neutral color for other operationsreturn 'border-l-border-muted'}++export function splitSqlStatements(sql: string): string[] {+ // Enhanced tokenizer that handles:+ // - Single-quoted strings: '...' (with '' escaping)+ // - Double-quoted strings: "..." (with "" escaping)+ // - Dollar-quoted strings: $tag$...$tag$+ // - Line comments: -- (until end of line)+ // - Block comments: /* ... */ (may be multiline)+ // - Semicolons: ;+ const tokens =+ sql.match(+ /'([^']|'')*'|"([^"]|"")*"|\$[a-zA-Z0-9_]*\$[\s\S]*?\$[a-zA-Z0-9_]*\$|--[^\r\n]*|\/\*[\s\S]*?\*\/|;|[^'"$;\-\/]+|./g+ ) || []++ const statements: string[] = []+ let current = ''++ for (const token of tokens) {+ if (token === ';') {+ if (current.trim()) statements.push(current.trim())+ current = ''+ } else {+ current += token+ }+ }++ if (current.trim()) {+ statements.push(current.trim())+ }++ return statements+}diff --git a/apps/studio/components/interfaces/SQLEditor/SQLEditor.tsx b/apps/studio/components/interfaces/SQLEditor/SQLEditor.tsxindex 8557a1b6643..c58b1f93a4b 100644--- a/apps/studio/components/interfaces/SQLEditor/SQLEditor.tsx+++ b/apps/studio/components/interfaces/SQLEditor/SQLEditor.tsx@@ -6,7 +6,12 @@ import { useRouter } from 'next/router'import { useCallback, useEffect, useMemo, useRef, useState } from 'react'import { toast } from 'sonner'-import { IS_PLATFORM, LOCAL_STORAGE_KEYS, useParams } from 'common'+import { IS_PLATFORM, LOCAL_STORAGE_KEYS, useFlag, useParams } from 'common'+import {+ isExplainQuery,+ isExplainSql,+ splitSqlStatements,+} from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.utils'import { SIDEBAR_KEYS } from 'components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider'import ResizableAIWidget from 'components/ui/AIEditor/ResizableAIWidget'import { GridFooter } from 'components/ui/GridFooter'@@ -93,6 +98,7 @@ export const SQLEditor = () => {const getImpersonatedRoleState = useGetImpersonatedRoleState()const databaseSelectorState = useDatabaseSelectorStateSnapshot()const { isHipaaProjectDisallowed } = useOrgAiOptInLevel()+ const showPrettyExplain = useFlag('ShowPrettyExplain')const {sourceSqlDiff,@@ -119,6 +125,7 @@ export const SQLEditor = () => {const [queryHasDestructiveOperations, setQueryHasDestructiveOperations] = useState(false)const [queryHasUpdateWithoutWhere, setQueryHasUpdateWithoutWhere] = useState(false)const [showWidget, setShowWidget] = useState(false)+ const [activeUtilityTab, setActiveUtilityTab] = useState<string>('results')// generate a new snippet title and an id to be used for new snippets. The dependency on urlId is to avoid a bug which// shows up when clicking on the SQL Editor while being in the SQL editor on a random snippet.@@ -151,7 +158,17 @@ export const SQLEditor = () => {const { mutate: sendEvent } = useSendEventMutation()const { mutate: execute, isPending: isExecuting } = useExecuteSqlMutation({onSuccess(data, vars) {- if (id) snapV2.addResult(id, data.result, vars.autoLimit)+ if (id) {+ snapV2.addResult(id, data.result, vars.autoLimit)++ if (showPrettyExplain && isExplainQuery(data.result)) {+ snapV2.addExplainResult(id, data.result)+ setActiveUtilityTab('explain')+ } else if (activeUtilityTab === 'explain') {+ // If on Explain tab but ran a non-EXPLAIN query, switch to Results tab+ setActiveUtilityTab('results')+ }+ }// revalidate lint queryqueryClient.invalidateQueries({ queryKey: lintKeys.lint(ref) })@@ -194,6 +211,21 @@ export const SQLEditor = () => {},})+ const { mutate: executeExplain, isPending: isExplainExecuting } = useExecuteSqlMutation({+ onSuccess(data) {+ if (id) {+ snapV2.addExplainResult(id, data.result)+ setActiveUtilityTab('explain')+ }+ },+ onError(error) {+ if (id) {+ snapV2.addExplainResultError(id, error)+ setActiveUtilityTab('explain')+ }+ },+ })+const setAiTitle = useCallback(async (id: string, sql: string) => {try {@@ -334,6 +366,72 @@ export const SQLEditor = () => {])+ const executeExplainQuery = useCallback(async () => {+ if (isDiffOpen) return++ // use the latest state+ const state = getSqlEditorV2StateSnapshot()+ const snippet = state.snippets[id]++ if (editorRef.current !== null && !isExplainExecuting && project !== undefined) {+ const editor = editorRef.current+ const selection = editor.getSelection()+ const selectedValue = selection ? editor.getModel()?.getValueInRange(selection) : undefined++ const sql = snippet+ ? (selectedValue || editorRef.current?.getValue()) ?? snippet.snippet.content?.sql+ : selectedValue || editorRef.current?.getValue()++ // Check for multiple statements - EXPLAIN only works on a single statement+ const statements = splitSqlStatements(sql)+ if (statements.length > 1) {+ snapV2.addExplainResultError(id, {+ message:+ 'EXPLAIN only works on a single SQL statement. Please select just one query to analyze.',+ })+ setActiveUtilityTab('explain')+ return+ }++ if (lineHighlights.length > 0) {+ editor?.deltaDecorations(lineHighlights, [])+ setLineHighlights([])+ }++ const impersonatedRoleState = getImpersonatedRoleState()+ const connectionString = databases?.find(+ (db) => db.identifier === databaseSelectorState.selectedDatabaseId+ )?.connectionString+ if (!isValidConnString(connectionString)) {+ return toast.error('Unable to run query: Connection string is missing')+ }++ // Wrap the query with EXPLAIN ANALYZE only if it's not already an EXPLAIN query+ const explainSql = isExplainSql(sql) ? sql : `EXPLAIN ANALYZE ${sql}`++ executeExplain({+ projectRef: project.ref,+ connectionString: connectionString,+ sql: wrapWithRoleImpersonation(explainSql, impersonatedRoleState),+ isRoleImpersonationEnabled: isRoleImpersonationEnabled(impersonatedRoleState.role),+ handleError: (error) => {+ throw error+ },+ })+ }+ }, [+ isDiffOpen,+ id,+ isExplainExecuting,+ project,+ executeExplain,+ getImpersonatedRoleState,+ databaseSelectorState.selectedDatabaseId,+ databases,+ lineHighlights,+ snapV2,+ ])+const handleNewQuery = useCallback(async (sql: string, name: string) => {if (!ref) return console.error('Project ref is required')@@ -807,11 +905,15 @@ export const SQLEditor = () => {<UtilityPanelid={id}isExecuting={isExecuting}+ isExplainExecuting={isExplainExecuting}isDisabled={isDiffOpen}hasSelection={hasSelection}prettifyQuery={prettifyQuery}executeQuery={executeQuery}+ executeExplainQuery={executeExplainQuery}onDebug={onDebug}+ activeTab={activeUtilityTab}+ onActiveTabChange={setActiveUtilityTab}/>)}</ResizablePanel>diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsxindex df65ad64d7e..222fb6ab931 100644--- a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx@@ -12,10 +12,6 @@ import {copyToClipboard,} from 'ui'import { CellDetailPanel } from './CellDetailPanel'-import { ExplainHeader } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.Header'-import { ExplainVisualizer } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer'-import { useFeatureFlags, useFlag } from 'common'-import { isExplainQuery } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.utils'function formatClipboardValue(value: any) {if (value === null) return ''@@ -28,12 +24,6 @@ function formatClipboardValue(value: any) {const Results = ({ rows }: { rows: readonly any[] }) => {const [expandCell, setExpandCell] = useState(false)const [cellPosition, setCellPosition] = useState<{ column: any; row: any; rowIdx: number }>()- const [showRaw, setShowRaw] = useState(false)-- const showPrettyExplain = useFlag('ShowPrettyExplain')-- // Check if this is an EXPLAIN query result- const isValidExplainQuery = isExplainQuery(rows)const formatter = (column: any, row: any) => {const cellValue = row[column]@@ -116,39 +106,6 @@ const Results = ({ rows }: { rows: readonly any[] }) => {}})- // Show pretty explain query results as diagram- if (showPrettyExplain && isValidExplainQuery) {- if (showRaw) {- return (- <div className="bg-studio border-t h-full flex flex-col">- <ExplainHeader mode="raw" onToggleMode={() => setShowRaw(false)} />- <div className="flex-grow overflow-auto">- <DataGrid- columns={columns}- rows={rows}- className="h-full flex-grow border-t-0"- rowClass={() => '[&>.rdg-cell]:items-center'}- onSelectedCellChange={setCellPosition}- onCellKeyDown={handleCopyCell}- />- <CellDetailPanel- column={cellPosition?.column.name ?? ''}- value={cellPosition?.row?.[cellPosition.column.name]}- visible={expandCell}- onClose={() => setExpandCell(false)}- />- </div>- </div>- )- }-- return (- <div className="h-full flex flex-col">- <ExplainVisualizer rows={rows} onShowRaw={() => setShowRaw(true)} />- </div>- )- }-return (<>{rows.length === 0 ? (diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityActions.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityActions.tsxindex 93147e806ca..ac0cae6e8f3 100644--- a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityActions.tsx+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityActions.tsx@@ -67,7 +67,7 @@ const UtilityActions = ({const removeFavorite = () => snapV2.removeFavorite(id)const onSelectDatabase = (databaseId: string) => {- snapV2.resetResult(id)+ snapV2.resetResults(id)setLastSelectedDb(databaseId)}diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityPanel.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityPanel.tsxindex e1554bca526..68f98ad63a7 100644--- a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityPanel.tsx+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityPanel.tsx@@ -1,6 +1,6 @@import { toast } from 'sonner'-import { useParams } from 'common'+import { useFlag, useParams } from 'common'import { DownloadResultsButton } from 'components/ui/DownloadResultsButton'import { useContentUpsertMutation } from 'data/content/content-upsert-mutation'import { Snippet } from 'data/content/sql-folders-query'@@ -11,16 +11,21 @@ import { TabsContent_Shadcn_, TabsList_Shadcn_, TabsTrigger_Shadcn_, Tabs_Shadcnimport { ChartConfig } from './ChartConfig'import UtilityActions from './UtilityActions'import UtilityTabResults from './UtilityTabResults'+import { UtilityTabExplain } from './UtilityTabExplain'export type UtilityPanelProps = {id: stringisExecuting?: boolean+ isExplainExecuting?: booleanisDebugging?: booleanisDisabled?: booleanhasSelection: booleanprettifyQuery: () => voidexecuteQuery: () => void+ executeExplainQuery: () => voidonDebug: () => void+ activeTab?: string+ onActiveTabChange?: (tab: string) => void}const DEFAULT_CHART_CONFIG: ChartConfig = {@@ -35,20 +40,33 @@ const DEFAULT_CHART_CONFIG: ChartConfig = {const UtilityPanel = ({id,isExecuting,+ isExplainExecuting,isDebugging,isDisabled,hasSelection,prettifyQuery,executeQuery,+ executeExplainQuery,onDebug,+ activeTab = 'results',+ onActiveTabChange,}: UtilityPanelProps) => {const { ref } = useParams()const { data: org } = useSelectedOrganizationQuery()const snapV2 = useSqlEditorV2StateSnapshot()+ const showPrettyExplain = useFlag('ShowPrettyExplain')const snippet = snapV2.snippets[id]?.snippetconst result = snapV2.results[id]?.[0]+ const handleTabChange = (tab: string) => {+ // When switching to the explain tab, trigger the explain query+ if (tab === 'explain') {+ executeExplainQuery()+ }+ onActiveTabChange?.(tab)+ }+const { mutate: sendEvent } = useSendEventMutation()const { mutate: upsertContent } = useContentUpsertMutation({@@ -110,12 +128,22 @@ const UtilityPanel = ({}return (- <Tabs_Shadcn_ defaultValue="results" className="w-full h-full flex flex-col">+ <Tabs_Shadcn_+ value={activeTab}+ onValueChange={handleTabChange}+ className="w-full h-full flex flex-col"+ ><TabsList_Shadcn_ className="flex justify-between gap-2 px-4 overflow-x-auto min-h-[42px]"><div className="flex items-center gap-4"><TabsTrigger_Shadcn_ className="py-3 text-xs" value="results"><span className="translate-y-[1px]">Results</span></TabsTrigger_Shadcn_>+ {/* Only show Explain tab if ShowPrettyExplain flag is on */}+ {showPrettyExplain && (+ <TabsTrigger_Shadcn_ className="py-3 text-xs" value="explain">+ <span className="translate-y-[1px]">Explain</span>+ </TabsTrigger_Shadcn_>+ )}<TabsTrigger_Shadcn_ className="py-3 text-xs" value="chart"><span className="translate-y-[1px]">Chart</span></TabsTrigger_Shadcn_>@@ -164,6 +192,13 @@ const UtilityPanel = ({/></TabsContent_Shadcn_>+ {/* Only render Explain tab content if ShowPrettyExplain flag is on */}+ {showPrettyExplain && (+ <TabsContent_Shadcn_ asChild value="explain" className="mt-0 flex-grow">+ <UtilityTabExplain id={id} isExecuting={isExplainExecuting} />+ </TabsContent_Shadcn_>+ )}+<TabsContent_Shadcn_ asChild value="chart" className="mt-0 flex-grow"><ChartConfig results={result} config={chartConfig} onConfigChange={onConfigChange} /></TabsContent_Shadcn_>diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabExplain.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabExplain.tsxnew file mode 100644index 00000000000..e799c83ca56--- /dev/null+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabExplain.tsx@@ -0,0 +1,106 @@+import { Loader2 } from 'lucide-react'+import { useState } from 'react'++import CopyButton from 'components/ui/CopyButton'+import { ExplainVisualizer } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer'+import { ExplainHeader } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.Header'+import { isExplainQuery } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.utils'+import { useSqlEditorV2StateSnapshot } from 'state/sql-editor-v2'+import { Tooltip, TooltipContent, TooltipTrigger } from 'ui'+import Results from './Results'++export type UtilityTabExplainProps = {+ id: string+ isExecuting?: boolean+}++export function UtilityTabExplain({ id, isExecuting }: UtilityTabExplainProps) {+ const snapV2 = useSqlEditorV2StateSnapshot()+ const explainResult = snapV2.explainResults[id]+ const [mode, setMode] = useState<'visual' | 'raw'>('visual')++ if (isExecuting) {+ return (+ <div className="flex items-center gap-x-4 px-6 py-4 bg-table-header-light [[data-theme*=dark]_&]:bg-table-header-dark">+ <Loader2 size={14} className="animate-spin" />+ <p className="m-0 border-0 font-mono text-sm">Running EXPLAIN ANALYZE...</p>+ </div>+ )+ }++ if (explainResult?.error) {+ const formattedError = (explainResult.error?.formattedError?.split('\n') ?? []).filter(+ (x: string) => x.length > 0+ )++ return (+ <div className="bg-table-header-light [[data-theme*=dark]_&]:bg-table-header-dark overflow-y-auto">+ <div className="flex flex-row justify-between items-start py-4 px-6 gap-x-4">+ <div className="flex flex-col gap-y-1">+ {formattedError.length > 0 ? (+ formattedError.map((x: string, i: number) => (+ <pre key={`error-${i}`} className="font-mono text-sm text-wrap">+ {x}+ </pre>+ ))+ ) : (+ <p className="font-mono text-sm tracking-tight">+ Error: {explainResult.error?.message}+ </p>+ )}+ </div>++ <div className="flex items-center gap-x-2">+ {formattedError.length > 0 && (+ <Tooltip>+ <TooltipTrigger>+ <CopyButton iconOnly type="default" text={formattedError.join('\n')} />+ </TooltipTrigger>+ <TooltipContent side="bottom" align="center">+ <span>Copy error</span>+ </TooltipContent>+ </Tooltip>+ )}+ </div>+ </div>+ </div>+ )+ }++ if (!explainResult || explainResult.rows.length === 0) {+ return (+ <div className="bg-table-header-light [[data-theme*=dark]_&]:bg-table-header-dark overflow-y-auto">+ <p className="m-0 border-0 px-4 py-4 text-sm text-foreground-light">+ No execution plan available. The query will be analyzed when you switch to this tab.+ </p>+ </div>+ )+ }++ const isValidExplain = isExplainQuery(explainResult.rows)++ if (!isValidExplain) {+ return (+ <div className="bg-table-header-light [[data-theme*=dark]_&]:bg-table-header-dark overflow-y-auto">+ <p className="m-0 border-0 px-4 py-4 text-sm text-foreground-light">+ Unable to parse explain results. Please try running the query again.+ </p>+ </div>+ )+ }++ const toggleMode = () => setMode(mode === 'visual' ? 'raw' : 'visual')++ return (+ <div className="h-full flex flex-col">+ {mode === 'visual' ? (+ <ExplainVisualizer rows={explainResult.rows} onShowRaw={toggleMode} id={id} />+ ) : (+ <>+ <ExplainHeader mode="raw" onToggleMode={toggleMode} id={id} rows={explainResult.rows} />+ <Results rows={explainResult.rows} />+ </>+ )}+ </div>+ )+}diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabResults.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabResults.tsxindex 7b52fd47632..31cd91d7926 100644--- a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabResults.tsx+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/UtilityTabResults.tsx@@ -138,7 +138,7 @@ const UtilityTabResults = forwardRef<HTMLDivElement, UtilityTabResultsProps>(type="default"onClick={() => {state.setSelectedDatabaseId(ref)- snapV2.resetResult(id)+ snapV2.resetResults(id)}}>Switch to primary databasediff --git a/apps/studio/state/sql-editor-v2.ts b/apps/studio/state/sql-editor-v2.tsindex 671153c60c6..fc6e4c45f96 100644--- a/apps/studio/state/sql-editor-v2.ts+++ b/apps/studio/state/sql-editor-v2.ts@@ -5,6 +5,7 @@ import { proxy, ref, snapshot, subscribe, useSnapshot } from 'valtio'import { devtools, proxyMap } from 'valtio/utils'import { DiffType } from 'components/interfaces/SQLEditor/SQLEditor.types'+import type { QueryPlanRow } from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.types'import { upsertContent, UpsertContentPayload } from 'data/content/content-upsert-mutation'import { contentKeys } from 'data/content/keys'import { createSQLSnippetFolder } from 'data/content/sql-folder-create-mutation'@@ -53,6 +54,13 @@ export const sqlEditorState = proxy({autoLimit?: number}[]},+ // Explain results, if any, for a snippet+ explainResults: {} as {+ [snippetId: string]: {+ rows: QueryPlanRow[]+ error?: { message: string; formattedError?: string }+ }+ },// Synchronous saving of folders and snippets (debounce behavior)// key is the snippet id, value is shouldInvalidateneedsSaving: proxyMap<string, boolean>([]),@@ -83,6 +91,7 @@ export const sqlEditorState = proxy({sqlEditorState.snippets[snippet.id] = { projectRef, splitSizes: [50, 50], snippet }sqlEditorState.results[snippet.id] = []+ sqlEditorState.explainResults[snippet.id] = { rows: [] }sqlEditorState.savingStates[snippet.id] = 'IDLE'},@@ -154,6 +163,9 @@ export const sqlEditorState = proxy({const { [id]: result, ...otherResults } = sqlEditorState.resultssqlEditorState.results = otherResults+ const { [id]: explainResult, ...otherExplainResults } = sqlEditorState.explainResults+ sqlEditorState.explainResults = otherExplainResults+if (!skipSave) sqlEditorState.needsSaving.delete(id)},@@ -255,6 +267,24 @@ export const sqlEditorState = proxy({sqlEditorState.results[id] = []}},++ addExplainResult: (id: string, results: QueryPlanRow[]) => {+ // Use ref() to prevent Valtio from creating proxies for each row object+ sqlEditorState.explainResults[id] = { rows: ref(results) }+ },++ addExplainResultError: (id: string, error: { message: string; formattedError?: string }) => {+ sqlEditorState.explainResults[id] = { rows: ref([]), error }+ },++ resetExplainResult: (id: string) => {+ sqlEditorState.explainResults[id] = { rows: [] }+ },++ resetResults: (id: string) => {+ sqlEditorState.resetResult(id)+ sqlEditorState.resetExplainResult(id)+ },})// ========================================================================diff --git a/apps/studio/tests/features/explain-visualizer/ExplainVisualizer.utils.test.ts b/apps/studio/tests/features/explain-visualizer/ExplainVisualizer.utils.test.tsnew file mode 100644index 00000000000..15aa91be03b--- /dev/null+++ b/apps/studio/tests/features/explain-visualizer/ExplainVisualizer.utils.test.ts@@ -0,0 +1,216 @@+import { describe, test, expect } from 'vitest'+import {+ splitSqlStatements,+ isExplainQuery,+ isExplainSql,+ formatNodeDuration,+} from 'components/interfaces/ExplainVisualizer/ExplainVisualizer.utils'++describe('isExplainQuery', () => {+ test('returns true for valid EXPLAIN result rows', () => {+ const rows = [{ 'QUERY PLAN': 'Seq Scan on users' }]+ expect(isExplainQuery(rows)).toBe(true)+ })++ test('returns false for empty array', () => {+ expect(isExplainQuery([])).toBe(false)+ })++ test('returns false for regular query results', () => {+ const rows = [{ id: 1, name: 'John' }]+ expect(isExplainQuery(rows)).toBe(false)+ })+})++describe('isExplainSql', () => {+ test('returns true for EXPLAIN queries', () => {+ expect(isExplainSql('EXPLAIN SELECT * FROM users')).toBe(true)+ expect(isExplainSql('explain analyze SELECT * FROM users')).toBe(true)+ expect(isExplainSql(' EXPLAIN SELECT 1')).toBe(true)+ })++ test('returns false for non-EXPLAIN queries', () => {+ expect(isExplainSql('SELECT * FROM users')).toBe(false)+ expect(isExplainSql('INSERT INTO users VALUES (1)')).toBe(false)+ })+})++describe('formatNodeDuration', () => {+ test('returns "-" for undefined', () => {+ expect(formatNodeDuration(undefined)).toBe('-')+ })++ test('formats seconds for large values', () => {+ expect(formatNodeDuration(1500)).toBe('1.50s')+ })++ test('formats milliseconds for medium values', () => {+ expect(formatNodeDuration(25.5)).toBe('25.50ms')+ })++ test('formats microseconds for small values', () => {+ expect(formatNodeDuration(0.0005)).toBe('0.5µs')+ })+})++describe('splitSqlStatements', () => {+ test('splits multiple statements by semicolon', () => {+ const sql = 'SELECT * FROM users; SELECT * FROM orders;'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT * FROM users')+ expect(result[1]).toBe('SELECT * FROM orders')+ })++ test('handles single statement', () => {+ const sql = 'SELECT * FROM users'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(1)+ expect(result[0]).toBe('SELECT * FROM users')+ })++ test('ignores semicolons inside single quotes', () => {+ const sql = "SELECT * FROM users WHERE name = 'foo;bar'; SELECT 1"+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe("SELECT * FROM users WHERE name = 'foo;bar'")+ })++ test('ignores semicolons inside dollar quotes', () => {+ const sql = 'SELECT $$ text with ; semicolon $$; SELECT 1'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT $$ text with ; semicolon $$')+ })++ test('returns empty array for empty input', () => {+ expect(splitSqlStatements('')).toHaveLength(0)+ expect(splitSqlStatements(' ')).toHaveLength(0)+ })++ test('ignores semicolons inside line comments', () => {+ const sql = 'SELECT * FROM users -- this is a comment; with semicolon'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(1)+ expect(result[0]).toBe('SELECT * FROM users -- this is a comment; with semicolon')+ })++ test('treats semicolons after line comments as separators', () => {+ const sql = 'SELECT * FROM users -- comment\n; SELECT * FROM orders'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT * FROM users -- comment')+ expect(result[1]).toBe('SELECT * FROM orders')+ })++ test('ignores semicolons inside block comments', () => {+ const sql = `SELECT * FROM users /* single-line; comment */ WHERE id = 1;+SELECT * FROM orders+/* multi-line comment+ with semicolon; inside+ multiple lines */+WHERE status = 'active'`+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT * FROM users /* single-line; comment */ WHERE id = 1')+ expect(result[1]).toContain('/* multi-line comment')+ expect(result[1]).toContain('with semicolon; inside')+ })++ test('handles mixed line comments and real semicolons', () => {+ const sql = `SELECT * FROM users -- first query; fake semicolon+; SELECT * FROM orders -- another comment; fake+WHERE status = 'active';`+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toContain('SELECT * FROM users')+ expect(result[0]).toContain('-- first query; fake semicolon')+ expect(result[1]).toContain('SELECT * FROM orders')+ expect(result[1]).toContain("WHERE status = 'active'")+ })++ test('handles mixed block comments and real semicolons', () => {+ const sql = 'SELECT 1; /* comment; with semicolon */ SELECT 2;'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT 1')+ expect(result[1]).toBe('/* comment; with semicolon */ SELECT 2')+ })++ test('handles multiple consecutive line comments', () => {+ const sql = `-- Comment 1; with semicolon+-- Comment 2; another semicolon+SELECT * FROM users`+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(1)+ expect(result[0]).toContain('-- Comment 1; with semicolon')+ expect(result[0]).toContain('-- Comment 2; another semicolon')+ expect(result[0]).toContain('SELECT * FROM users')+ })++ test('handles comments at end of statement', () => {+ const sql = `SELECT * FROM users; -- end comment; with semicolon+SELECT * FROM orders /* block comment; */`+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT * FROM users')+ expect(result[1]).toContain('SELECT * FROM orders')+ expect(result[1]).toContain('/* block comment; */')+ })++ test('handles complex mix of strings, comments, and semicolons', () => {+ const sql = `-- Initial comment; with semicolon+SELECT 'string; with semicolon' FROM users /* block; comment */;+-- Next query+SELECT "quoted; identifier" FROM orders -- line; comment+WHERE data = $$ dollar; quote $$;`+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(2)+ expect(result[0]).toContain("SELECT 'string; with semicolon' FROM users")+ expect(result[0]).toContain('/* block; comment */')+ expect(result[1]).toContain('SELECT "quoted; identifier" FROM orders')+ expect(result[1]).toContain('$$ dollar; quote $$')+ })++ test('handles statement that is only a comment', () => {+ const sql = '-- Just a comment; with semicolon'+ const result = splitSqlStatements(sql)++ expect(result).toHaveLength(1)+ expect(result[0]).toBe('-- Just a comment; with semicolon')+ })++ test('handles empty statements between semicolons', () => {+ const sql = 'SELECT 1;; SELECT 2'+ const result = splitSqlStatements(sql)++ // Empty statements are filtered out by trim()+ expect(result).toHaveLength(2)+ expect(result[0]).toBe('SELECT 1')+ expect(result[1]).toBe('SELECT 2')+ })++ test('handles EXPLAIN queries with comments (single statement verification)', () => {+ const sql = `-- Query to analyze; note the semicolon+EXPLAIN ANALYZE+SELECT * FROM users+WHERE created_at > NOW() - INTERVAL '1 day' -- last 24 hours; active users`+ const result = splitSqlStatements(sql)++ // EXPLAIN only works with single statements - verify comments don't cause false splits+ expect(result).toHaveLength(1)+ expect(result[0]).toContain('EXPLAIN ANALYZE')+ })+})