MySQL & MariaDB Query Plan Visualizer

Visualize MySQL EXPLAIN ANALYZE FORMAT=JSON and MariaDB ANALYZE FORMAT=JSON output as interactive SVG charts. Five views, one parser, zero external dependencies.

Inspired by Brendan Gregg's FlameGraph and Tanel Poder's SQL Plan FlameGraphs.

Start here: Why: 4x fewer tokens · Output preview · Install · Output types · Live demos · Learn the algorithms
For humans: Quick start · Live-connection mode · HTML report · Environment advisor
For agents & CI: JSON sidecar · Compare / diff · digest / advise / check · MCP server
Reference: Requirements · CLI reference · Troubleshooting · Documentation

Every operator now carries a Big O chip: O(log n + k), O(n · log m), O(n · m), … with a color-coded severity ramp.

New in 2.0 — myflames is now built for the AI era. The digest command emits a compact, source-grounded plan digest to hand an LLM instead of raw EXPLAIN JSON (and digest --cost shows the tokens and dollars you save); new diff / check / advise subcommands serve agents and CI; an MCP server (myflames-mcp) lets agents call myflames directly; and every HTML report gains an "Agent-ready" panel. The worked example below is the headline. See the full CHANGELOG entry.

Why this works: a raw EXPLAIN ANALYZE FORMAT=JSON plan is mostly structure, not information. The same field names (cost_info, used_columns, actual_rows, actual_loops, …) repeat for every operator, nested levels deep, and the LLM pays for all of it and must parse it before it can reason. myflames does that parsing once and hands the model only the facts that decide the answer — the summary, the warnings, and the fix. Same answer, a quarter of the tokens.

Every number here is measured against a live MySQL 8.4, not estimated (the walkthrough reproduces it with one Docker script). The query scans every order because orders.total isn't indexed:

SELECT o.id, o.total, oi.quantity, p.name
FROM orders o
JOIN order_items oi ON oi.order_id = o.id
JOIN products p     ON p.id = oi.product_id
WHERE o.total > 450
ORDER BY o.total DESC
LIMIT 50;

You run EXPLAIN ANALYZE FORMAT=JSON …, copy the ~5.5 KB of deeply nested JSON, paste it in, and ask "why is this slow, and how do I make it faster?" That prompt is 2,110 tokens on Claude (1,420 on GPT-4o) — and the model parses all that structure before it can reason.

myflames digest plan.json | pbcopy    # then paste

The digest is 521 tokens and already names the diagnosis and the fix — this is real output:

# Query plan analysis (myflames digest)
engine mysql | 9 ops | depth 6 | 1.819 ms | rows 50 sent / 12,004 examined

SUMMARY: Query scans 1 table and sorts the result; examines ~12,004 rows to
return 50 in 1.8 ms. Main finding: no index covers (total) on orders.

WARNINGS (2):
- [warn/full_scan] Full table scan: orders (12000 rows) (@ Table scan [orders])
- [warn/filesort] 1 sort operation(s) — 15 rows; may use disk-based filesort (@ Sort)

INDEXES:
- CREATE INDEX idx_orders_total ON orders (total);

We actually asked Claude (Opus 4.8) the question both ways. It reached the same diagnosis and the same fix either way. From the digest:

The bottleneck is the first access path on orders: a full table scan — MySQL reads all ~12,000 rows because there's no index on total. You return 50 rows but examine 12,004, a ~240:1 read-to-return ratio. The surviving rows are then filesorted… The joins are fine. Fix: CREATE INDEX idx_orders_total ON orders (total);

Same quality answer — for a quarter of the input tokens:

On Opus 4.8 input pricing that's $0.008 saved per query ($7.90 per 1,000); on Sonnet 4.6, ~$4.80 per 1,000 — and you save output tokens and round-trips too, because the answer is already in the digest. On bigger, messier plans the saving climbs higher.

Numbers measured 2026-06-05 against Claude Opus 4.8 and the GPT tokenizer. The offline heuristic is the zero-dependency default and slightly over-counts JSON.

digest --cost uses an offline heuristic by default — no key, no network. For exact counts add a tokenizer:

myflames digest explain.json --cost --tokenizer claude   # Anthropic count_tokens; needs myflames[tokens] + your ANTHROPIC_API_KEY
myflames digest explain.json --cost --tokenizer gpt      # tiktoken; exact for GPT, keyless; needs myflames[gpt]

Your ANTHROPIC_API_KEY is read from the environment at call time and never stored; if it's unset, --tokenizer claude falls back to the estimate with a one-line note. count_tokens is free. Full setup is in the walkthrough.

Reproduce it against a live MySQL 8.4 with the step-by-step walkthrough. Want to skip the copy/paste? Register the MCP server and your agent calls myflames itself.

Four views of the same query, each annotated with Big O complexity:

Flame graph — time hierarchy + severity dots	Bar chart — slowest ops with a complexity column
Treemap — corner chips on larger tiles	Diagram — Visual Explain style, Big O per node

New in 1.4.0 — every operator carries a vetted Big O complexity chip (see the shared complexity legend that renders at the bottom of every view). Open any HTML demo below to hover and inspect: O(log n + k) for index lookups, O(n log n) for filesort, O(n · m) when a nested loop has no inner index, and so on.

pip install myflames          # or: pipx install myflames  (Homebrew / PEP 668)

Pure Python 3.7+ stdlib. No external dependencies.

myflames sample.json > query.svg                  # SVG flame graph
myflames --output report.html sample.json         # self-contained HTML report

Or connect straight to a live MySQL / MariaDB server — same flags as the mysql CLI:

myflames -h db.example.com -u admin -p -D mydb \
  -e 'SELECT * FROM orders WHERE user_id = 1' \
  --output report.html
# → report.html  — progressive-UX HTML with advisor warnings
# → report.json  — v1 schema sidecar for AI agents / CI / jq

Preview	Type	Best for	Command
	Flame graph	Full execution hierarchy, time distribution	myflames explain.json
	Bar chart	Finding the slowest individual operations	myflames --type bargraph explain.json
	Treemap	Comparing relative cost at a glance	myflames --type treemap explain.json
	Diagram	Join order & access paths (Visual Explain style)	myflames --type diagram explain.json
—	Execution tree	Collapsible per-subtree with self/total time	myflames --type tree explain.json

Not sure which view? Run myflames guide.

Every view includes a Query Analysis panel with optimizer features detected, warnings (full table scans, hash joins, BNL buffers, temp tables, filesorts) and concrete tuning suggestions.

All demos →

Interactive features (zoom, search, tooltips) need the HTML wrapper or GitHub Pages — raw GitHub URLs block inline scripts.

Interactive, offline-first HTML lessons that animate MySQL 8.4 and MariaDB 11.x internals with correct cost models. Every lesson ships with in-page sliders — no CLI flags, no re-running. Each is a single self-contained HTML file (no external scripts/styles/fonts) you can drop in a Slack DM or attach to a ticket:

myflames teach btree -o btree.html && open btree.html   # one lesson
myflames teach --index -o teach/index.html              # the catalog hub

21 lessons in four families — browse them all at vgrippa.github.io/myflames/teach/.

• Python 3.7+ (no extra packages)
• MySQL 8.4 through 9.7+ with SET explain_json_format_version = 2 — including the hypergraph optimizer and the 9.x query_plan envelope (verified against real 9.7), or
• MariaDB 10.11+ / 11.4 / 11.8+ (supports ANALYZE FORMAT=JSON and SHOW ANALYZE FORMAT=JSON FOR <conn_id> out of the box)

-- MySQL
EXPLAIN ANALYZE FORMAT=JSON SELECT ... ;
-- MariaDB
ANALYZE FORMAT=JSON SELECT ... ;

# Save to a file and render
mysql -u user -p mydb -s -N -r -e "EXPLAIN ANALYZE FORMAT=JSON SELECT ..." > explain.json
myflames explain.json > query.svg

# Or pipe directly
mysql -u user -p mydb -N -e "EXPLAIN ANALYZE FORMAT=JSON SELECT ..." | myflames > query.svg

# Self-contained HTML report
myflames --output report.html explain.json

myflames auto-strips MySQL CLI quirks (table borders, EXPLAIN headers, escaped newlines, BOM), so plain -e also works.

Skip the two-step workflow — connect directly. Same flags for MySQL 8.4 and MariaDB:

# Local
myflames -h 127.0.0.1 -u root -p'password' -D mydb -e 'SELECT ...' --output report.html

# AWS RDS with full TLS verification
myflames -h my-db.rds.amazonaws.com -u admin -p \
  --ssl-mode=VERIFY_IDENTITY --ssl-ca=/path/to/global-bundle.pem \
  -D prod -e 'SELECT ...' --output report.html

In live mode myflames (1) connects through the real mysql / mariadb client binary (every auth plugin the server supports — no PyMySQL), (2) runs EXPLAIN ANALYZE FORMAT=JSON, (3) collects SHOW CREATE TABLE, row/byte counts, and a filtered SHOW SESSION VARIABLES snapshot, (4) feeds everything through the environment advisor, and (5) emits the HTML report + JSON sidecar.

Password handling: the password is written to a mode-0600 --defaults-extra-file and never appears on argv or in env vars. Skip any collection step with --no-collect-schema, --no-collect-stats, --no-collect-variables.

myflames --output report.html explain.json
myflames --type diagram --output report.html explain.json

A self-contained file you can attach to a ticket or paste into Confluence. Built for three audiences at once:

• Newcomers — plain-English executive summary, a single "Fix first" primary action card above the fold (always carries a Why: clause, even when the advisor doesn't supply one), glossary chips on every jargon term (filesort, hash join, BNL, MRR, ICP, …) that anchor-link to a glossary aside and to the matching myflames teach lesson via a sibling Learn → button. Below the glossary, a centralized myteach hub section links to the catalog of all 21 algorithm lessons and surfaces the lessons relevant to this plan as quick chips.
• Senior DBAs — every metric, warning and SET / CREATE INDEX / ALTER TABLE recommendation in copy-paste-able <pre><code> blocks. The Collected environment panel renders byte-sized variables in human form (innodb_buffer_pool_size: 128 MB) with raw bytes in the tooltip, collapses optimizer_switch into a 27-flag chip list color-coded by =on / =off, and turns each touched table into a click-to-expand accordion that reveals columns (with types + NULL badges) and indexes (with PK / UNIQUE / INDEX badges + column tuples) inline. A two-row sticky header carries engine / version / operator-count / total-time / generated-at metadata pulled from the same source the JSON sidecar emits.
• AI agents / tools — a <script type="application/ld+json"> block in <head> wrapping the v1 sidecar payload as { "@context": "https://myflames.dev/ns/v1", "@type": "QueryPlanAnalysis", "@id": ... }, a <link rel="alternate" type="application/json"> pointing at the sibling JSON sidecar, and stable node_id references across warnings / operator_complexities / plan_tree so external consumers can correlate without OCR'ing SVG text.

Every --output writes a stable, versioned, machine-readable sidecar next to the main file:

myflames --output report.html explain.json
# → report.html  report.json

{
  "$schema": "https://myflames.dev/schemas/sidecar-v1.json",
  "schema_version": "1.3",
  "source": {"type": "live", "engine": "mysql", "engine_version": "8.4.8"},
  "plan_summary": { "total_time_ms": 12.4, "operator_count": 12, ... },
  "plan_tree":   { "node_id": "n:a676d93c9d98", "short_label": "Limit",
                   "children": [ ... ] },
  "warnings":    [ {"severity": "error", "category": "nonsargable_join", ...} ],
  "suggestions": [ {"severity": "high", "category": "rewrite", "action": "...", "why": "..."} ],
  "primary_action": {"ref": "suggestions[0]"},
  "operator_complexities": [ {"node_id": "n:5416613cb59f", "big_o": "O(n · m)", ...} ],
  "environment_findings":  [ {"rule_id": "FLUSH_LOG_COMMIT_2", "severity": "high", ...} ],
  "collected": { "variables": {...}, "stats": {...}, "schema": {...} }
}

The HTML report wraps this same payload in a JSON-LD envelope (@context: https://myflames.dev/ns/v1, @type: QueryPlanAnalysis) so search crawlers and LLM retrieval pipelines parse it correctly, and links to the sibling sidecar via <link rel="alternate" type="application/json">. The published JSON Schema lives at docs/schemas/sidecar-v1.json.

For before/after diffs, myflames compare before.json after.json --output diff.html emits a separate sidecar at docs/schemas/compare-v1.json (schema_version: "compare-1.0") carrying summary{regressions, improvements, unchanged} and per-operator deltas keyed by the same node_id. CI can gate on summary.regressions == 0 without scraping HTML.

Read it with jq — no HTML parsing needed:

jq '.suggestions[0] | .action + " — Why: " + .why' report.json
jq '.warnings[] | select(.category == "env")'      report.json

Suppress with --no-sidecar, or point at an explicit path with --sidecar /tmp/plan.json. See myflames/output_sidecar.py for the full schema.

With access to server state (live mode, or any caller populating analysis), myflames runs rules matching plan signals against collected server state and emits tuning suggestions grounded in the MySQL cost model:

Every suggestion carries a Why: clause — enforced by a test so no rule ships without a cost-model justification.

myflames compare before.json after.json --output diff.html   # HTML report
myflames diff    before.json after.json --digest             # token-cheap text diff for an LLM
myflames diff    before.json after.json --json               # structured delta (compare-1.0)

Shows total time delta, per-operator self-time/rows/loops changes, new or removed full table scans, and new/resolved warnings. (diff is an alias of compare.)

myflames serves AI agents and pipelines, not just human eyes:

myflames digest plan.json              # compact LLM-ready digest (pipe to your model)
myflames digest plan.json --cost       # tokens + $ saved vs the raw plan; --tokenizer claude|gpt, --json
myflames advise plan.json --json       # ranked warnings + suggestions, each with a confidence
myflames check  plan.json --fail-on full_scan,filesort   # CI gate: exit 1 if a trigger matches

Exit-code contract: 0 success · 1 a gate/finding tripped · 2 bad input. That makes check a drop-in pre-commit/CI guard and an agent-loop primitive.

Let Claude Code, Cursor, or any MCP client call myflames directly — no copy/paste, no OCR'ing an SVG:

pip install 'myflames[mcp]'
claude mcp add myflames -- myflames-mcp

Exposed tools: analyze_plan, digest_plan, compare_plans, explain_optimizer_switch (source-verified), and explain_query (connect + EXPLAIN ANALYZE live). The agent reasons over the 335-token digest instead of the 2,000+-token raw plan. The MCP transport is an optional extra; the core package stays stdlib-only.

myflames [options] [explain.json]
myflames -h HOST [-P PORT] -u USER [-p[PASS]] -D DB -e 'SQL' -o OUT

myflames compare before.json after.json --output diff.html   # before/after (alias: diff)
myflames digest explain.json [--cost]   # LLM-ready digest (--cost: token/$ saving)
myflames advise explain.json [--json]   # ranked warnings + suggestions
myflames check  explain.json --fail-on full_scan,filesort    # CI gate (exit code)
myflames teach  btree -o btree.html     # interactive algorithm lesson
myflames guide                          # which view should I use?

Full help: myflames --help. See Agent and CI subcommands for the digest/advise/check details.

All views support Ctrl+F regex search. The bar chart, treemap, diagram, and execution tree use click-to-pin details strips (text is always selectable). The diagram has +/− zoom buttons, drag-to-pan, and double-click to reset. Execution tree has Expand/Collapse All. See each demo for the full interaction set.

"Failed to parse EXPLAIN JSON" — use EXPLAIN ANALYZE FORMAT=JSON, not just EXPLAIN FORMAT=JSON. The ANALYZE keyword is required for timing data.

Interactive features not working — open the .html wrapper, not the raw .svg. Browsers block inline scripts in SVGs loaded from raw.githubusercontent.com.

macOS PEP 668 — use pipx install myflames instead of pip install.

End users never need anything beyond pip install myflames + Python 3.7. If you want to edit the project's source — write a new lesson, add an advisor rule, modify the Tier-1 animation runtime, or run the headless animation harness — see CONTRIBUTING.md.

• Brendan Gregg — FlameGraph implementation (pure-Python port in myflames/flamegraph.py)
• Tanel Poder — SQL Plan FlameGraph concept and label format

Extends Brendan Gregg's FlameGraph project. See docs/cddl1.txt (CDDL 1.0).