# Review a PostgreSQL query-plan report safely

Canonical: https://githtml.com/guides/review-postgresql-query-plan-report
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

A query-plan review needs the query, relevant schema, database version, data characteristics, and the conditions under which the plan was obtained. Separate estimated behavior from observed execution. PostgreSQL's EXPLAIN ANALYZE actually runs the statement, so reviewing a saved report is different from authorizing someone to execute a query.

## Check the report's measurement context

Ask whether the plan is estimated or execution-backed and which database version produced it. Identify representative parameter values and whether sensitive values were redacted. An illustrative report for an export-history query should include filtering, ordering, and the relevant indexes rather than only a cropped plan image. PostgreSQL's documentation explains plan nodes and their estimates; those details must be interpreted alongside the actual data distribution. A plan from a tiny development dataset may not answer a question about a large operational table.

## Compare estimates with the question being asked

Look for the part of the plan relevant to the reported symptom: rows examined, join behavior, sorting, or repeated work. Do not assume that an index scan is always desirable or that a sequential scan is automatically a defect. If execution measurements are present, distinguish per-loop values and repeated execution where the report requires that interpretation. An illustrative review question is whether the estimated selectivity matches the observed result size. Record uncertainty instead of prescribing a new index based on a single unfamiliar label.

1. Context: verify query text, version, schema, parameters, and data scale.
2. Evidence: identify estimated versus measured values and their units.
3. Question: connect the suspected cost to the actual user-visible problem.

## Request a safe follow-up rather than improvising

If evidence is insufficient, ask the database owner for an approved representative test. Do not run EXPLAIN ANALYZE against an arbitrary production statement from a phone or casually shared document. Even read-oriented work can consume resources, and modifying statements have additional effects. A proposed index or rewrite needs validation for correctness and operational cost, not merely a nicer-looking plan. Keep the HTML report's query and plan as readable escaped text, and include the collection date so reviewers understand that the document is a measurement snapshot.

## Sources and further reading

- [PostgreSQL: Using EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html)
- [Google SRE: Effective Troubleshooting](https://sre.google/sre-book/effective-troubleshooting/)

## Related guides

- [Trace data flow through a technical review document](https://githtml.com/guides/trace-data-flow-in-technical-review)
- [Review performance claims without being fooled by one fast run](https://githtml.com/guides/review-performance-claims-with-distributions)
- [Review test coverage by reading assertions, not percentages](https://githtml.com/guides/review-test-coverage-by-assertions)
- [Review an asynchronous job design for retries and ownership](https://githtml.com/guides/review-asynchronous-job-design)

Editorial approach: https://githtml.com/guides/about