Getting Started

Install myflames, generate your first flame graph, and understand a query plan in under 5 minutes.

Prerequisites

Installation

1

Install from PyPI

pip install myflames

On macOS with PEP 668 restrictions, use pipx:

pipx install myflames
2

Verify the installation

myflames --help
myflames guide    # shows which view to use

Your first flame graph (file mode)

1

Capture an EXPLAIN ANALYZE plan

# MySQL 8.4+
mysql -u user -p mydb -s -N -r -e \
  "EXPLAIN ANALYZE FORMAT=JSON SELECT * FROM orders WHERE user_id = 1" \
  > explain.json

# MariaDB 10.11+
mariadb -u user -p mydb -s -N -r -e \
  "ANALYZE FORMAT=JSON SELECT * FROM orders WHERE user_id = 1" \
  > explain.json
Use EXPLAIN ANALYZE (with ANALYZE), not just EXPLAIN. The ANALYZE keyword is required for timing data.
2

Render a flame graph

# SVG to stdout
myflames explain.json > query.svg

# Self-contained HTML report (recommended)
myflames --output report.html explain.json
# Creates: report.html + report.json (machine-readable sidecar)
3

Open in your browser

open report.html    # macOS
xdg-open report.html  # Linux

The HTML report includes interactive zoom, search (Ctrl+F), tooltips, and a Query Analysis panel with tuning suggestions.

Live connection mode (skip the file)

Connect directly to a running MySQL/MariaDB server using the same flags as the mysql CLI:

myflames -h 127.0.0.1 -u root -p -D mydb \
  -e 'SELECT * FROM orders WHERE user_id = 1' \
  --output report.html

In live mode, myflames:

  1. Connects through the real mysql/mariadb client binary (supports all auth plugins)
  2. Runs EXPLAIN ANALYZE FORMAT=JSON for you
  3. Collects SHOW CREATE TABLE, row counts, and session variables
  4. Feeds everything through the environment advisor
  5. Emits an HTML report + JSON sidecar with tuning suggestions
Password security: the password is written to a mode-0600 temporary file and never appears in ps, env vars, or logs.

TLS connections (e.g., AWS RDS)

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

Try other view types

myflames --type bargraph  explain.json > bar.svg    # slowest ops first
myflames --type treemap   explain.json > tree.svg   # area = cost
myflames --type diagram   explain.json > diag.svg   # Visual Explain flow
myflames --type tree      explain.json > exec.svg   # collapsible tree

See the View Types guide for when to use each one.

Compare before vs after

myflames compare before.json after.json --output diff.html

Shows total time delta, per-operator changes, new/resolved warnings, and new/removed full table scans.

Use it with an AI agent or CI

myflames isn't only for human eyes. It projects a plan into forms an agent or pipeline can consume directly — instead of pasting verbose EXPLAIN JSON into a model and paying to have it parsed.

# Hand an LLM a compact, source-grounded digest instead of the raw plan
myflames digest explain.json | pbcopy

# See how many tokens (and dollars) that saves vs pasting the raw plan
myflames digest explain.json --cost

# Ranked warnings + fixes for an agent to act on (machine-readable)
myflames advise explain.json --json

# CI / pre-commit gate: exit 1 if the plan trips a trigger
myflames check explain.json --fail-on full_scan,filesort

Agents can also call myflames directly over MCP:

pip install 'myflames[mcp]'
claude mcp add myflames -- myflames-mcp
Exact token counts are optional: pip install 'myflames[tokens]' + --tokenizer claude (uses your own ANTHROPIC_API_KEY), or pip install 'myflames[gpt]' + --tokenizer gpt (keyless). The default counter is an offline heuristic that needs no key and no network. See the Agent & CI subcommands reference.

Learn the algorithms

myflames includes 9 interactive lessons that animate MySQL internals with correct cost models:

myflames teach btree -o btree.html && open btree.html

See the full catalog at Teach Lessons.

Next steps