Django Query Profiling

Use this skill to turn a vague slow-Django report into a specific queryset, SQL statement, and reproducible scenario.

Workflow

1. Start from the user-visible slow path.

• Record the URL, API action, background task, management command, or report.
• Capture request parameters, user or tenant shape, pagination state, and data volume.

1. Collect production or staging evidence.

• Prefer APM transaction traces when available.
• Use database slow-query logs for SQL that is slow independent of Python.
• Use Django Debug Toolbar for server-rendered pages in local development.
• For APIs or jobs, add targeted query logging around the suspicious block.

1. Map SQL back to Django code.

• Search model table names and column names.
• Inspect view get_queryset(), serializer fields, template loops, managers, model properties, and signal handlers.
• Check whether related-object access happens after the initial queryset was evaluated.

1. Reproduce locally or in a safe shell.

• Use production-like row counts when possible.
• Disable unrelated instrumentation and debug-only middleware when measuring.
• Keep a repeatable script, test, or shell snippet that exercises the slow path.

1. Route the fix.

• Query count issue: use django-orm-query-optimization.
• One slow SQL statement: use django-query-plan-reading.
• Large loops or writes: use django-queryset-batch-processing.

See tooling-and-reproduction.md for concrete profiling snippets and pitfalls.

Good Evidence

• Query count before/after for the specific path.
• The slow SQL or normalized SQL fingerprint.
• Stack or code pointer that explains where the SQL originates.
• Timing from the same environment and representative data shape.

Verification

Do not finish profiling with only a hunch. Finish with a named queryset, code path, and command or request that another agent can re-run.