Skip to content

Add EXPLAIN plan visualization with diagram, tree, and raw views#641

Merged
datlechin merged 11 commits intomainfrom
feat/explain-visualization
Apr 8, 2026
Merged

Add EXPLAIN plan visualization with diagram, tree, and raw views#641
datlechin merged 11 commits intomainfrom
feat/explain-visualization

Conversation

@datlechin
Copy link
Copy Markdown
Collaborator

Summary

Adds visual EXPLAIN plan rendering for PostgreSQL and MySQL. Users can now see query execution plans as interactive diagrams or tree views instead of raw text.

Three view modes (segmented control)

  • Diagram: Canvas-based boxes with arrows, color-coded by cost (green to red), zoom controls, click node for detail popover
  • Tree: Native OutlineGroup list with expandable nodes, alternating rows, click to select and see detail panel
  • Raw: Original monospace text output (JSON for PostgreSQL/MySQL)

PostgreSQL

  • EXPLAIN button dropdown: "EXPLAIN" and "EXPLAIN ANALYZE"
  • Uses EXPLAIN (FORMAT JSON) / EXPLAIN (ANALYZE, FORMAT JSON) for structured parsing
  • Shows planning time and execution time from ANALYZE

MySQL/MariaDB

  • Plain "Explain" button (no dropdown since MariaDB doesn't support EXPLAIN ANALYZE)
  • Uses EXPLAIN FORMAT=JSON for structured parsing

Architecture

  • QueryPlanNode / QueryPlan data model with cost fraction computation
  • QueryPlanParser protocol with PostgreSQL JSON, MySQL JSON, and SQLite parsers
  • Databases routed through variant-based EXPLAIN path via explainVariants on DriverPlugin
  • Tab state: explainPlan: QueryPlan? on QueryTab, cleared on normal Execute

New files

  • TablePro/Models/Query/QueryPlan.swift
  • TablePro/Core/Services/Query/QueryPlanParser.swift
  • TablePro/Views/QueryPlan/QueryPlanTreeView.swift
  • TablePro/Views/QueryPlan/QueryPlanDiagramView.swift

Test plan

  • PostgreSQL: Explain dropdown > EXPLAIN > verify diagram with color-coded nodes
  • PostgreSQL: Explain dropdown > EXPLAIN ANALYZE > verify actual timing shown
  • PostgreSQL: Toggle Diagram / Tree / Raw views
  • PostgreSQL: Click node in tree > verify detail panel
  • PostgreSQL: Click node in diagram > verify detail popover
  • MySQL/MariaDB: Plain Explain button (no dropdown) > verify JSON parsed into tree
  • After EXPLAIN, click Execute > verify data grid returns (no stuck explain view)
  • Status bar hidden during EXPLAIN view
  • ClickHouse: Verify existing multi-variant EXPLAIN still works

@datlechin datlechin merged commit 732264d into main Apr 8, 2026
1 check passed
@datlechin datlechin deleted the feat/explain-visualization branch April 8, 2026 16:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant