/django

name: django
description: Use when building Django applications. Covers ORM query performance, model design, migrations, Django REST Framework, security defaults, and testing.
metadata:
  category: backend
  version: 1.0.0
  tags: [django, orm, drf, migrations, python]

Django

Purpose

Build Django applications that use the ORM efficiently and the framework's security defaults correctly. Most Django performance problems are one missing `select_related` away from being fixed.

When to Use

• Building or reviewing a Django application or DRF API.
• Diagnosing slow views caused by the ORM.
• Writing migrations that must run against a large table.
• Auditing Django security settings before launch.

Capabilities

• ORM: `select_related`, `prefetch_related`, annotations, subqueries, bulk operations.
• Model design: constraints, indexes, and validation at the database level.
• Migrations, including zero-downtime patterns for large tables.
• Django REST Framework: serializers, viewsets, permissions, pagination.
• Security: the settings that must not be wrong in production.

Inputs

• The application, its models, and the slow view or endpoint if there is one.
• Table sizes, for anything involving migrations.
• Deployment environment and settings module.

Outputs

• Views with a bounded, predictable query count.
• Migrations that do not lock a large table.
• Settings that pass `manage.py check --deploy`.

Workflow

1. **Count the queries** — `assertNumQueries` in tests, `django-debug-toolbar` in development. An N+1 is invisible until you count. 2. **Fix them at the queryset** — `select_related` for forward foreign keys (a join), `prefetch_related` for reverse and many-to-many (a second query). Not both, not neither. 3. **Push work into the database** — `annotate`, `aggregate`, `bulk_create`, `update`. A loop that saves each object issues one query per iteration. 4. **Constrain at the database** — `UniqueConstraint`, `CheckConstraint`. Application-level validation does not survive concurrency or a shell script. 5. **Migrate safely** — On a large table, adding a column with a default rewrites it. Add nullable, backfill in batches, then set the default. 6. **Check the deploy settings** — `DEBUG = False`, `ALLOWED_HOSTS`, `SECURE_*`, `SECRET_KEY` from the environment.

Best Practices

• `queryset.count()` inside a template loop is a query per iteration. Annotate the count once.
• `.only()` and `.defer()` are traps if the deferred field is later accessed — each access is a new query. Use them only when profiling shows they help.
• Never use `objects.all()` in a view without pagination. It will work fine until the table has a million rows.
• Signals create action at a distance and make tests fragile. Prefer explicit calls in a service function.
• `bulk_create` does not call `save()` or fire signals — which is the point, and also the footgun. Know which behavior you need.
• Run `manage.py check --deploy` in CI. It catches the settings that turn into vulnerabilities.

Examples

**Removing an N+1 and pushing aggregation into the database:**

# Before: 1 query for orders + 1 per customer + 1 per line-item count = ~2N+1.
orders = Order.objects.filter(status="open")
for order in orders:
    print(order.customer.name, order.items.count())

# After: 2 queries total, count computed by the database.
orders = (
    Order.objects
    .filter(status="open")
    .select_related("customer")                       # join
    .annotate(item_count=Count("items"))              # aggregate in SQL
)
for order in orders:
    print(order.customer.name, order.item_count)

**Database-level constraint rather than a hopeful `clean()`:**

class Subscription(models.Model):
    tenant = models.ForeignKey(Tenant, on_delete=models.CASCADE)
    period_start = models.DateField()
    period_end = models.DateField()

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=["tenant", "period_start"],
                name="uniq_subscription_period",
            ),
            models.CheckConstraint(
                check=models.Q(period_end__gt=models.F("period_start")),
                name="period_end_after_start",
            ),
        ]

Notes

• `select_related` on a nullable foreign key produces a LEFT JOIN and can multiply rows through a chain. Check the generated SQL with `str(qs.query)` when the query count looks right but the latency does not.
• Adding an index on a large PostgreSQL table blocks writes unless you use `AddIndexConcurrently` inside a `NonAtomic` migration.
• DRF's `ModelSerializer` will happily expose every field on the model. Always list `fields` explicitly; `__all__` is how private fields end up in a public API.