django-orm-patterns

Django ORM Patterns

This skill covers Django ORM model definitions, query patterns, and database-level options. Apply alongside django-plugin:django-conventions when implementing features.

Role split:

• django-architect uses this skill for model definitions — fields, __str__, choices, class Meta ordering, custom managers, and query patterns.
• django-migrations-specialist uses this skill for field finalization — setting max_digits, on_delete, db_index, Meta.indexes, Meta.constraints — before running makemigrations.

1. Detection

Check the Django version in requirements.txt or pyproject.toml before writing constraint code — Meta.constraints using CheckConstraint uses condition= in Django 5.1+ and check= in Django 4.x. When uncertain, check the installed version with python manage.py --version or read the pinned version from the dependency file.

2. Model definition patterns

Use TextChoices for string-typed status/type fields. Write a meaningful __str__. Always specify class Meta ordering.

from django.db import models
from django.contrib.auth import get_user_model

User = get_user_model()


class Order(models.Model):
    class Status(models.TextChoices):
        PENDING = 'pending', 'Pending'
        PROCESSING = 'processing', 'Processing'
        SHIPPED = 'shipped', 'Shipped'
        CANCELLED = 'cancelled', 'Cancelled'

    user = models.ForeignKey(User, on_delete=models.PROTECT, related_name='orders')
    product = models.CharField(max_length=255)
    qty = models.PositiveIntegerField()
    unit_price = models.DecimalField(max_digits=10, decimal_places=2)
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.PENDING)
    notes = models.TextField(blank=True, default='')
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ['-created_at']
        indexes = [
            models.Index(fields=['status', 'created_at']),
        ]
        constraints = [
            models.UniqueConstraint(fields=['user', 'reference'], name='unique_user_reference'),
            # Django 5.1+: condition=; Django 4.x: check=
            models.CheckConstraint(condition=models.Q(qty__gt=0), name='orders_order_qty_positive'),
        ]

    def __str__(self) -> str:
        return f'Order #{self.pk} — {self.product} ({self.get_status_display()})'

    @property
    def is_cancellable(self) -> bool:
        return self.status in (self.Status.PENDING, self.Status.PROCESSING)