Django Query Profiling
Use this skill to turn a vague slow-Django report into a specific queryset, SQL statement, and reproducible scenario.
Workflow
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.
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.
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.
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.
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.
1---2name: django-query-profiling3description: Find the Django ORM code and request path responsible for slow SQL by using APM traces, slow query logs, Django Debug Toolbar, query logging, and local reproduction. Use when a Django database performance issue is suspected but the exact queryset, view, serializer, template, or job causing it is not yet proven.4license: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 version: "0.1.0"8 displayName: Django Query Profiling9 category: Django10 tags: django,database,profiling,apm,debug-toolbar11---1213# Django Query Profiling1415Use this skill to turn a vague slow-Django report into a specific queryset, SQL statement, and reproducible scenario.1617## Workflow18191. Start from the user-visible slow path.20 - Record the URL, API action, background task, management command, or report.21 - Capture request parameters, user or tenant shape, pagination state, and data volume.22232. Collect production or staging evidence.24 - Prefer APM transaction traces when available.25 - Use database slow-query logs for SQL that is slow independent of Python.26 - Use Django Debug Toolbar for server-rendered pages in local development.27 - For APIs or jobs, add targeted query logging around the suspicious block.28293. Map SQL back to Django code.30 - Search model table names and column names.31 - Inspect view `get_queryset()`, serializer fields, template loops, managers, model properties, and signal handlers.32 - Check whether related-object access happens after the initial queryset was evaluated.33344. Reproduce locally or in a safe shell.35 - Use production-like row counts when possible.36 - Disable unrelated instrumentation and debug-only middleware when measuring.37 - Keep a repeatable script, test, or shell snippet that exercises the slow path.38395. Route the fix.40 - Query count issue: use `django-orm-query-optimization`.41 - One slow SQL statement: use `django-query-plan-reading`.42 - Large loops or writes: use `django-queryset-batch-processing`.4344See [tooling-and-reproduction.md](references/tooling-and-reproduction.md) for concrete profiling snippets and pitfalls.4546## Good Evidence4748- Query count before/after for the specific path.49- The slow SQL or normalized SQL fingerprint.50- Stack or code pointer that explains where the SQL originates.51- Timing from the same environment and representative data shape.5253## Verification5455Do not finish profiling with only a hunch. Finish with a named queryset, code path, and command or request that another agent can re-run.
ConcertoNotes