Everything ExplainSQL accepts, in one place. explainsql --help and explainsql COMMAND --help print the same information in your terminal.
explainsql [OPTIONS] [FILE] read a plan, or run a statement with -d
explainsql diff BEFORE [AFTER] compare two plans
explainsql check PATHS… check plans in CI
explainsql logs FILES… plan changes in auto_explain logs
explainsql top -d DATABASE the costliest statements from pg_stat_statements
explainsql requests FILES… N+1 loops in statement logs
explainsql anonymize [FILE] a plan with names and values replaced
Reads a plan from FILE, or from standard input when FILE is missing or -, and opens it in the viewer or prints a report. With -d and -f or -c, it runs a statement itself instead (connected mode).
The plan file: JSON or text, as EXPLAIN printed it or wrapped in psql output, a log entry, a GUI client’s cell or a Markdown fence. Standard input when missing or -.
--print
Print a report instead of opening the viewer. This happens anyway when the output is not a terminal.
--format text|md|json
The report’s format. Default: text.
--color auto|always|never
When to color the text report. auto (the default) colors when the output is a terminal and NO_COLOR is not set.
--theme dark|light
The terminal’s background, for the viewer’s colors. Default: dark.
--demo
Show the bundled sample plan instead of reading one.
--pager
Act as psql’s pager: open plans in the viewer, pass any other output to $EXPLAINSQL_PAGER, $PAGER or less -S.
--debug-parse
Print what the parser understood instead of the analysis. With --format json, the parsed plan as JSON.
--fail-on low|medium|high
With a printed report, exit with 1 when a finding is at least this severe.
The database: a URL, key=value settings or a name. PG* variables, the service file and ~/.pgpass apply as in psql.
-f, --query-file FILE
Run the statement in this file.
-c, --command SQL
Run this statement.
--no-analyze
Show the estimated plan only, without running the statement.
--timeout SECONDS
Stop a run after this many seconds. Default: 30.
--allow-dml
Also run statements that modify data or lock rows, still in a transaction that is rolled back, and report what their writes cost.
--allow-ddl
To test an index without HypoPG, build it in a transaction that is rolled back. With --prove, also drop the indexes that keep updates from being HOT. Both block the table while they run.
--prove
With --print: test each suggested index, and with --allow-ddl, rerun a non-HOT update without its blocking indexes.
--why-not [TABLE]
With --print: ask the planner why it chose its plan for the slowest nodes, or for the scans of TABLE (a table or index name).
--measure
Measure the alternatives of --why-not and y, and the differing plans of --params, with EXPLAIN ANALYZE instead of only estimating them.
--runs N
How many measured runs to compare for --prove and --measure, each side after one warm-up run. The median counts. Default: 1.
Checks plans in CI: each against its findings and against the plan locked for it. Exits with 0 when every plan passed, 1 when one failed, 2 on an error.
Option
What it does
PATHS
Plan files, or with -d, SQL files. Directories are searched for *.json and *.txt plans, or *.sql statements.
-d, --dbname DATABASE
Run the SQL files against this database.
--fail-on low|medium|high
Also fail a plan with a finding at least this severe.
--strict
Also fail a plan whose shape changed, even when it is not worse.
--lock FILE
The file of locked plans. Default: explainsql.lock.
--update
Lock the plans as they are now instead of checking them. Other plans in the file are kept.
--prove
With -d: test the suggested indexes of each plan that failed, with HypoPG.
--no-analyze
With -d: plan the statements without running them.
--allow-dml
With -d: also run statements that modify data or lock rows, rolled back.
--timeout SECONDS
With -d: stop a statement after this many seconds. Default: 30.