pg_explain
Retrieve query plans for SQL statements. Optionally run EXPLAIN ANALYZE or test hypothetical indexes without persisting changes.
Instructions
Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set analyze: true to run the query with EXPLAIN ANALYZE - for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is text (default) or json. Pass the raw SQL (not an EXPLAIN-prefixed statement). Set hypothetical_indexes to a list of {table, columns, using?} to ask the planner 'what would the plan be if these indexes existed?' -- requires the HypoPG extension (CREATE EXTENSION hypopg). The hypothetical indexes are torn down at the end of the call, never touching real disk.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL statement to explain. Do NOT prefix with EXPLAIN. | |
| format | No | Output format. | text |
| params | No | Positional parameters referenced as $1, $2, ... in the SQL. | |
| analyze | No | Run EXPLAIN ANALYZE (actually executes the query). | |
| hypothetical_indexes | No | List of indexes the planner should pretend exist for this EXPLAIN. Requires the HypoPG extension. Indexes are session-scoped and reset at the end of the call. |