Skip to content

feat(explain): redesign EXPLAIN plan visualization with syntax highlighting #745

@NikolayS

Description

@NikolayS

Problem

EXPLAIN output in rpg is currently rendered as plain text — same as psql. For a DBA tool, this is a missed opportunity. The plan is hard to scan at a glance.

Goal

Make EXPLAIN output readable at terminal speed. Inspired by the PostgreSQL EXPLAIN dialect in Pygments (https://pygments.org/docs/lexers/#pygments.lexers.sql.PostgresExplainLexer) — borrow the token grammar and apply terminal colors.

Proposed visualization

Color-code the key elements:

  • Node type (Seq Scan, Index Scan, Hash Join, etc.) — bold/cyan
  • Cost () — dim, not important unless high
  • Actual time () — color-coded: green <10ms, yellow <100ms, red >100ms
  • Rows — highlight when estimate vs actual diverge significantly (>10x)
  • Filter / Index Cond — highlight in yellow (potential optimization target)
  • Buffers — highlight high shared_hit_blocks in a different shade
  • Nested loop with high loops — flag visually

The raw text structure (indentation, arrows) must be preserved — we only add color, never reformat.

Reference

Implementation hints

  • New module or extend src/explain/
  • Apply coloring only when stdout is a TTY (same guard as other highlighting)
  • Respect --no-highlight / no_highlight setting
  • Works for both inline EXPLAIN queries and the /explain AI command output

Acceptance criteria

  • Node types, costs, actual times, and filters are visually distinct
  • High row-estimate divergence (>10x) is highlighted
  • Coloring disabled correctly when --no-highlight is set or stdout is not a TTY
  • Tests for the highlighter (unit tests with sample EXPLAIN output strings)
  • Screenshot/recording in PR showing before/after

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions