django-perf-review

Django performance review

Contract

Inputs

Required: read access to the Django codebase under review (models, managers, querysets, views, DRF viewsets/serializers, signals, template tags). Optional: the specific app or module paths to bound scope; a running app or test suite for query-count confirmation; Django settings/INSTALLED_APPS for app discovery.

Procedure

1. Bound scope to the app or module paths the user named. If none named, ask once for the scope before scanning. Do not edit files. Done when: scope is named and bounded.
2. Enumerate ORM call sites: scan models, managers, views, DRF viewsets, serializers, signals, and template tags for queryset construction and relation access (.filter, .get, .exclude, .select_related, .prefetch_related, .values, .values_list, .annotate, .aggregate, .iterator, .exists, .count, .only, .defer, __ lookups, reverse managers, .related_model access). Done when: ORM call sites are enumerated.
3. Trace relation access per row: for each queryset, follow foreign-key, one-to-one, many-to-many, and reverse relations accessed inside loops, templates, serializer nested fields, or per-instance property access. Flag a relation access that runs one query per row when the relation is not loaded on that code path via select_related or prefetch_related. Done when: per-row relation access is traced.
4. Detect queryset misuse: querysets evaluated more than once on the same path, len(qs)/list(qs) before iteration, slicing after evaluation, .only()/.defer() that still triggers deferred-field loads. For .count() where .exists() would suffice, and for missing .iterator() on large result sets, require evidence of the result size before flagging: a query-plan row estimate, a .count() call result, a logged result count, or a user-confirmed cardinality. A .count() or missing .iterator() finding without result-size evidence is a candidate, not a validated finding. Done when: queryset misuse candidates are identified, with result-size evidence attached to every .count() and .iterator() flag.
5. Detect unbounded reads: list/index views without pagination, admin actions without queryset scoping. For unindexed filter or order fields, require query-plan or data-cardinality evidence before flagging: an EXPLAIN output showing a sequential scan, a measured row count on the filtered column, or a user-confirmed table size. An unindexed-field finding without plan or cardinality evidence is a candidate, not a validated finding. Done when: unbounded reads are identified, with plan or cardinality evidence attached to every unindexed-field flag.
6. Validate every finding against the actual code path: cite file, line, the queryset expression, the relation access, and the per-row query it triggers. Confirm the relation is not already prefetched or selected on that exact path. A finding without a confirmed access path is not reported as validated. Done when: every reported finding has a confirmed access path.
7. Classify severity by impact and query-count growth: N+1 in a list/index/hot path is high (O(n) queries per request); per-request single-row access is medium; rare/admin-only path is low. State the growth as queries per request or per row. Done when: severity states query growth and path impact.
8. For each validated finding, give the concrete fix with the exact queryset rewrite: select_related for FK/one-to-one, prefetch_related or Prefetch for many-to-many/reverse, pagination, .iterator(), .only(), or a migration adding the index. Show the before and after queryset. Done when: each finding has an exact queryset rewrite.
9. Return the report. Do not apply fixes, run migrations, or modify the codebase. Done when: the report is returned without applying fixes.