Django Query Plan Reading

Use this skill when the expensive unit is a specific SQL statement or queryset. The goal is to explain why the database is doing work, not to guess from the ORM code.

Workflow

1. Get the exact query.

- Prefer the queryset that produced it. - If starting from logged SQL, include bound parameters or representative literals.

1. Generate a plan.

- Use queryset.explain() for ORM-owned SQL. - Use database EXPLAIN for raw SQL, views, materialized views, or SQL copied from logs. - Use analyze=True only in a safe environment because the database executes the query.

1. Read from the deepest node outward.

- Identify table scans, index scans, joins, sorts, aggregations, and limits. - Compare estimated rows with actual rows when using analyze. - Look for high-cost nodes that feed many rows to later nodes.

1. Decide the next change.

- Missing selective access path: use django-index-design. - Query shape prevents useful index access: rewrite filters, ordering, or join strategy. - Large unavoidable aggregation: consider django-db-side-computation or django-materialized-views. - Deep offset cost: use django-pagination-performance.

1. Re-run the same plan after the change.

- Compare scan type, row counts, sort nodes, heap fetches, buffers, planning time, and execution time.

See [explain-checklist.md](references/explain-checklist.md) for plan-reading cues and before/after review notes.

Safety Notes

• EXPLAIN ANALYZE executes the query. Avoid it for mutations, unsafe functions, and production paths unless you know the impact.
• A sequential scan is not automatically bad. It can be best when the table is small or the predicate returns much of the table.
• A used index is not automatically good. Random heap access, bad cardinality estimates, or a post-index sort can still dominate.

Verification

Finish with the before/after plan excerpt and a plain explanation of which node changed and why that matters.