Skip to main content
Show the execution plan for a SQL statement without running it.

​
Features

  • Never executes: Only ever compiles/plans the statement — safe to enable regardless of the source’s readonly setting
  • Per-dialect output: Uses EXPLAIN on PostgreSQL, MySQL, MariaDB, and SQL Server, EXPLAIN PLAN + DBMS_XPLAN on Oracle, and EXPLAIN QUERY PLAN on SQLite (bare EXPLAIN on SQLite returns low-level bytecode, not a readable plan)
  • Opt-in only: Not part of the default tool pair — must be explicitly enabled per source
explain_sql is opt-in. Unlike execute_sql and search_objects, it is not enabled automatically when a source has no [[tools]] entries — add it explicitly (see Enabling explain_sql below).

​
Usage

Pass a single SQL statement to explain. The tool adds the EXPLAIN prefix itself — do not include it in the input.
Only a single statement is accepted (no ;-separated batches), and the input must not itself begin with EXPLAIN or ANALYZE — both are rejected so the tool’s own EXPLAIN prefix can never combine with a smuggled ANALYZE to actually execute the statement.
Because plain EXPLAIN never executes the target statement, explain_sql is safe to run against write statements too. explain_sql on DELETE FROM users WHERE id = 1 returns the plan without deleting anything.

​
Enabling explain_sql

Add a [[tools]] entry with name = "explain_sql". It takes no other options — no readonly or max_rows — since it’s always read-only:
See Tool Configuration for how [[tools]] entries work across multiple sources.