The Complete Production SOP: How to Deploy and Run Django ORM Query Optimization & N+1 Prevention in Autonomous AI Agents
Step-by-step SOP to install and run Django ORM query optimization in Codex, Claude Code, and Cursor. Fix N+1 queries using select_related and prefetch_related.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate naive Django ORM queries when writing views, API serializers, or management commands. When iterating across foreign keys or many-to-many relationships (e.g., accessing 'post.author.profile' or 'post.tags.all()' inside a template or serializer loop), unguided LLMs default to standard evaluation loops. This introduces devastating N+1 query regressions, transforming a single API response into hundreds of sequential roundtrips to PostgreSQL or MySQL. Without a deterministic procedural boundary, agents also misapply relationship optimizers: attempting to use 'select_related' on reverse many-to-many tables (which raises runtime exceptions) or applying unconstrained 'prefetch_related' calls that pull thousands of unnecessary rows into memory. Furthermore, agents often overlook attribute projections, loading bulky JSONField and text blobs instead of leveraging 'only()' and 'defer()'. This skill establishes strict deterministic guardrails across Codex, Claude Code, Cursor, and Windsurf. It forces agents to classify model relationships prior to query generation, mandates custom 'Prefetch' objects for filtered reverse relations, and automatically runs query assertion checks using 'django.test.utils.CaptureQueriesContext' before finalizing code changes.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent's runtime directory to register trigger words and procedural SOP rules.
Agent runtimes such as Claude Code, Cursor, Codex, and Windsurf index skills through local manifests. By mounting the SKILL.md file directly into your workspace or user agent configuration folder, the agent automatically exposes triggers like 'fix n+1 query django orm' and 'select_related vs prefetch_related' to its intent matching system.
mkdir -p .cursor/skills/django-orm-select-related-prefetch && curl -fsSL https://askills.dev/api/skills/django-orm-select-related-prefetch/raw -o .cursor/skills/django-orm-select-related-prefetch/SKILL.md---
name: "django-orm-select-related-prefetch"
description: "Eliminate N+1 database queries and optimize heavy relational data loading in Django ORM."
metadata:
author: "Django"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "fix n+1 query django orm"
- "select_related vs prefetch_related"
- "django orm only defer"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---To save context tokens across multi-turn sessions, store SKILL.md in the workspace root; modern agents only pull the procedural SOP section into active context when the trigger pattern is detected.
Ensure permissions.fs_write is locked to 'workspace'. Setting permissions to global or shell_exec: true without sandboxing creates risks when agents generate migration code.
Environment Secrets & Dependency Validation
Ensure Django settings and database inspection utilities are configured without exposing credentials in prompts.
The optimization skill requires Django settings to execute database query audits. Ensure django-debug-toolbar or internal test runners are configured in your development virtual environment so that the agent can test queryset efficiency without mutating production credentials.
python -m pip install django-debug-toolbar pytest-django && python manage.py check --database default# Ensure database logging or debug toolbar is enabled locally
INTERNAL_IPS = ["127.0.0.1"]
INSTALLED_APPS += ["debug_toolbar"]
MIDDLEWARE = ["debug_toolbar.middleware.DebugToolbarMiddleware"] + MIDDLEWARENever paste database connection strings or SECRET_KEY into the prompt. Direct the agent to use DJANGO_SETTINGS_MODULE and local environment variables.
Verify that your virtualenv is activated in the agent terminal session; running manage.py checks under a mismatched Python binary triggers missing dependency exceptions.
Intent Matching & Query Transformation Execution
Trigger the agent using strict procedural syntax to transform unoptimized ORM lookups into JOINs and batch prefetches.
Provide the agent with explicit model schemas and target views. The agent evaluates foreign keys versus many-to-many fields, generates 'select_related' for single-valued relationships, and applies 'prefetch_related(Prefetch(...))' with custom querysets for filtered collections.
from django.db.models import Prefetch
from .models import Article, Comment
# Optimized: 2 total queries regardless of result count
articles = (
Article.objects.select_related('author', 'category')
.prefetch_related(
Prefetch(
'comments',
queryset=Comment.objects.filter(is_approved=True).select_related('user'),
)
)
.only('id', 'title', 'slug', 'author__username', 'category__name')
)Chain 'only()' or 'defer()' after 'select_related()' to minimize memory usage, but ensure required foreign key ID columns are not accidentally deferred, which triggers secondary queries.
Do not pass reverse ForeignKey or ManyToManyField names to 'select_related()'. Django will throw an immediate FieldError at query evaluation time.
Verification, Query Counting & Output Quality Gate
Validate query reduction using automated test assertions before merging agent changes.
Before accepting code from Codex or Claude Code, execute a test using 'assertNumQueries' or 'CaptureQueriesContext' to verify that the query count remains constant regardless of the number of records returned.
pytest -k test_article_list_query_countfrom django.test import TestCase
from django.test.utils import CaptureQueriesContext
from django.db import connection
from blog.models import Article, Author
class QueryOptimizationTest(TestCase):
def test_article_list_constant_query_count(self):
with CaptureQueriesContext(connection) as ctx:
list(Article.objects.select_related('author').all())
# Exactly 1 query executed with JOIN, zero N+1 queries
self.assertEqual(len(ctx.captured_queries), 1)Add 'assertNumQueries' tests to your CI/CD pipeline so any future PR that removes 'select_related' or 'prefetch_related' immediately fails before reaching staging.
Be aware that iterating over a queryset that utilizes 'iterator()' bypasses 'prefetch_related' cache storage in memory, leading to repeated queries if accessed multiple times.
Real-World Scenario: Eliminate 500+ Database Queries in an E-Commerce Order API Endpoint
“fix n+1 query django orm: Our OrderListView in orders/views.py is generating over 500 queries on a single request when rendering 50 orders with customer details, order items, and associated product categories. Apply select_related vs prefetch_related and django orm only defer rules to limit database hits to under 3 queries.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attempted to invoke select_related on a ManyToManyField or reverse relation, which requires SQL JOINs that Django ORM only supports via prefetch_related.
# Replace select_related with prefetch_related for M2M and reverse relationships
# BAD: Article.objects.select_related('tags')
# GOOD:
Article.objects.prefetch_related('tags')Root Cause: The agent used .only('title') on a model but omitted the underlying foreign key column (e.g. 'author_id') needed to hydrate author instances.
# Explicitly include the foreign key ID column or the related lookup in .only()
Article.objects.select_related('author').only('title', 'author__id', 'author__username')Frequently Asked Questions (Django ORM Query Optimization & N+1 Prevention SOP)
Q:Can I use Django ORM Query Optimization & N+1 Prevention across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres strictly to the universal SKILL.md specification. You can mount the identical manifest file in Codex (~/.codex/skills), Claude Code (~/.claude/skills), Cursor (.cursor/skills), and Windsurf (.windsurf/skills) without modifying any underlying directives.
Q:How does Django ORM Query Optimization & N+1 Prevention prevent context window overflow during long agent sessions?
Instead of prompting the agent with hundreds of lines of database documentation, the skill loads declarative frontmatter rules and triggers only when relevant keywords are invoked. It enforces concise query transformation patterns and provides concrete test assertions that prevent rambling conversational loops.
Q:Does this skill require escalated root or container permissions?
No. The skill has an audited security score of 98/100. It requires read-only context analysis and standard workspace file system writes (fs_write: 'workspace'). It explicitly disallows arbitrary shell execution and direct outbound network calls, running safely inside locked development containers.
Ready to equip your autonomous agent with Django ORM Query Optimization & N+1 Prevention?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.