#128 feat: add visual explain plan with AI analysis

[Anonymous]

Originally created by: debba

Summary

This PR introduces a full visual SQL EXPLAIN workflow across the editor and notebook experience.

Users can now open a dedicated Visual Explain modal for supported queries, inspect the execution plan as a graph or table, review the raw driver output, and optionally ask the configured AI provider for a plan analysis.

What Changed

Frontend

• added a new VisualExplainModal with:
• graph view for plan nodes and relationships
• tabular view for easier row-by-row inspection
• raw output view for direct driver output inspection
• AI analysis view backed by the configured AI provider
• added ExplainGraph, ExplainTableView, ExplainSummaryBar, and ExplainAiAnalysis components
• added reusable explain-plan utilities and types for layout, formatting, and node cost styling
• exposed the new Explain Plan action in both the SQL editor and notebook SQL cells
• added localized UI strings for English, Italian, Spanish, and Chinese
• extended AI settings with a dedicated prompt for explain-plan analysis

Backend / Tauri

• added the explain_query_plan command to execute and return a structured explain plan
• added the analyze_ai_explain_plan command to send the SQL query plus explain output to the configured AI provider
• added prompt configuration support for explain-plan analysis
• added explain-related models and driver capability plumbing needed by the frontend
• added cancellation handling around explain execution, aligned with existing query execution patterns

Driver Support

• PostgreSQL now returns parsed JSON explain plans, with optional ANALYZE and buffer data
• SQLite now exposes EXPLAIN QUERY PLAN output through the shared explain-plan model
• MySQL/MariaDB support was expanded significantly:
• server-version-aware capability detection
• smarter EXPLAIN ANALYZE usage when supported
• JSON explain parsing improvements
• better MariaDB handling for filesort, wrappers, temporary tables, and subquery cache patterns
• tabular explain fallback when richer formats are unavailable

Query Safety / UX

• added explainability checks so EXPLAIN only runs for supported statement types
• strips leading SQL comments before determining whether a query can be explained
• surfaces a localized error for non-explainable statements
• warns users when ANALYZE may execute data-modifying statements

Why

The existing SQL tooling could explain queries with AI, but it did not provide a native, structured way to inspect execution plans inside the app. This change closes that gap by combining:

• a visual representation for quick plan understanding
• a table/raw fallback for accuracy and debugging
• AI-assisted interpretation for users who want guidance on bottlenecks and indexing opportunities

Testing

• pnpm test --run tests/utils/explainPlan.test.ts tests/utils/sql.test.ts
• pnpm typecheck
• pnpm test:rust

Results

• frontend tests: 2 files passed, 66 tests passed
• Rust tests: 317 passed, 0 failed
• integration tests: existing MySQL/Postgres integration tests remain ignored

Notes

• This PR touches both frontend and backend because the feature requires new UI, shared plan models, new Tauri commands, and driver-specific explain parsing.
• The MySQL driver contains the largest part of the implementation due to compatibility handling across MySQL and MariaDB explain formats.

[Anonymous]

Originally posted by: kilo-code-bot[bot]

Code Review Summary

Status: 5 Issues Found | Recommendation: Address CRITICAL issues before merge

Overview

Severity	Count
CRITICAL	3
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

#### CRITICAL | File | Line | Issue | |------|------|-------| | `src-tauri/src/drivers/mysql/mod.rs` | 1072 | SQL Injection - query directly interpolated into SQL (also at 1103, 1136, 1169) | | `src-tauri/src/drivers/postgres/mod.rs` | 1033 | SQL Injection - query directly interpolated into SQL (also at 1035) | | `src-tauri/src/drivers/sqlite/mod.rs` | 585 | SQL Injection - query directly interpolated into SQL | #### WARNING | File | Line | Issue | |------|------|-------| | `src/components/modals/visual-explain/ExplainTableView.tsx` | 303 | React key collision risk with `name-i` pattern | #### SUGGESTION | File | Line | Issue | |------|------|-------| | `src-tauri/src/commands.rs` | 2127 | Double error logging - error logged and returned |

Incremental Review (commit 9eb814e)

**Files changed since last review:** - `src/components/modals/VisualExplainModal.tsx` - Added `t` to useCallback dependencies (fix applied) - `src/utils/sql.ts` - Comment cleanup **No new issues introduced.**

Files Reviewed (32 files)

**Backend (Rust):** - `src-tauri/src/drivers/mysql/mod.rs` - SQL injection in EXPLAIN queries - `src-tauri/src/drivers/postgres/mod.rs` - SQL injection in EXPLAIN queries - `src-tauri/src/drivers/sqlite/mod.rs` - SQL injection in EXPLAIN queries - `src-tauri/src/drivers/common.rs` - Added `is_explainable_query` check - `src-tauri/src/commands.rs` - Added `explain_query_plan` command - `src-tauri/src/ai.rs` - Added `analyze_ai_explain_plan` command - `src-tauri/src/config.rs` - Added explain plan prompt configuration **Frontend (TypeScript/React):** - `src/components/modals/VisualExplainModal.tsx` - Main modal component - `src/components/modals/visual-explain/ExplainTableView.tsx` - Table view with key collision risk - `src/components/modals/visual-explain/ExplainAiAnalysis.tsx` - AI analysis component - `src/components/modals/visual-explain/ExplainSummaryBar.tsx` - Summary bar component - `src/components/modals/visual-explain/ExplainGraph.tsx` - Graph visualization - `src/utils/explainPlan.ts` - Utilities for plan formatting - `src/utils/sql.ts` - Added `isExplainableQuery` and `stripLeadingSqlComments` - Plus 18 additional files with minor changes

Fix these issues in Kilo Cloud

---

_{Reviewed by kimi-k2.5-0127 · 405,793 tokens}