🗃️ Django Model Definition

What a Model Really Is

In Django, a model is a Python class that subclasses django.db.models.Model. Each model maps to one database table, and each class attribute you declare as a Field maps to one column. You describe your data in Python; Django generates the SQL, builds an object-oriented query API, wires up the admin, and produces forms — all from that single definition.

💡 A useful analogy: A model is like an architect's blueprint. The blueprint isn't the building — it's the authoritative description that everyone works from. Change the blueprint and the plumbing, wiring, and inspectors all follow. Change a Django model and its table, admin, forms, and validation all follow too.

This is the payoff of the DRY (Don't Repeat Yourself) principle: you define the shape of your data once, and Django derives everything else from it.

Defining Your First Model

Models live in an app's models.py. Here is a small, complete, modern example. Note the TextChoices enum (the current, readable way to declare choices in Django) and the __str__ method that gives each row a human-readable label.

from django.db import models
from django.conf import settings
from django.utils import timezone


class Article(models.Model):
    class Status(models.TextChoices):
        DRAFT = "draft", "Draft"
        PUBLISHED = "published", "Published"
        ARCHIVED = "archived", "Archived"

    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    content = models.TextField()
    status = models.CharField(
        max_length=10,
        choices=Status.choices,
        default=Status.DRAFT,
    )
    published_at = models.DateTimeField(default=timezone.now)
    author = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="articles",
    )
    is_featured = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

Field Types & Options

Each field type maps to a database column type and carries its own validation. Pick the most specific field that fits your data — a specific field gives you free validation and a better admin widget.

Field options

Options are keyword arguments that tune a field's behavior. The most important ones:

from django.core.validators import MinValueValidator, MaxValueValidator


class Product(models.Model):
    name = models.CharField(max_length=120, db_index=True)
    sku = models.CharField(max_length=32, unique=True)
    description = models.TextField(blank=True)                 # blank OK in forms
    price = models.DecimalField(max_digits=10, decimal_places=2)
    discount = models.DecimalField(
        max_digits=5, decimal_places=2, null=True, blank=True,  # optional in DB and forms
    )
    rating = models.IntegerField(
        default=0,
        validators=[MinValueValidator(0), MaxValueValidator(5)],
        help_text="A score from 0 to 5.",
    )

Model Relationships

Real data is connected. Django models three kinds of connection with three field types.

One-to-many — ForeignKey

One author writes many books; each book has one author. The ForeignKey lives on the "many" side.

class Author(models.Model):
    name = models.CharField(max_length=100)

    def __str__(self):
        return self.name


class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(
        Author,
        on_delete=models.CASCADE,
        related_name="books",   # author.books.all()
    )

    def __str__(self):
        return self.title

Many-to-many — ManyToManyField

An article can have many tags, and a tag can label many articles. Django creates a hidden join table for you.

class Tag(models.Model):
    name = models.CharField(max_length=50)
    slug = models.SlugField(unique=True)

    def __str__(self):
        return self.name


class Article(models.Model):
    title = models.CharField(max_length=200)
    tags = models.ManyToManyField(Tag, related_name="articles", blank=True)

Put the ManyToManyField on either model — Django exposes the relationship from both sides. Use blank=True (not null=True) to make a many-to-many optional; a join table with zero rows already means "no relations."

One-to-one — OneToOneField

A user has exactly one profile. This is effectively a ForeignKey with unique=True and is the standard way to extend a model without touching it.

class Profile(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="profile",
    )
    bio = models.TextField(blank=True)
    birth_date = models.DateField(null=True, blank=True)

    def __str__(self):
        return f"Profile for {self.user}"

Model Inheritance

Django offers three inheritance styles. By far the most common — and usually the one you want — is the abstract base class for sharing fields without creating an extra table.

Abstract base classes (share fields, no table)

class TimeStampedModel(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True          # no table is created for this model


class Article(TimeStampedModel):
    title = models.CharField(max_length=200)


class Comment(TimeStampedModel):
    body = models.TextField()

Both Article and Comment now have created_at/updated_at columns, defined in one place.

Multi-table inheritance (each model gets a table)

Here a child model links to its parent with an automatic one-to-one. Both tables exist. Useful, but adds a JOIN on every access — reach for it deliberately.

class Place(models.Model):
    name = models.CharField(max_length=100)
    address = models.CharField(max_length=200)


class Restaurant(Place):          # gets its own table + link to Place
    serves_pizza = models.BooleanField(default=False)

Proxy models (same table, new behavior)

A proxy changes Python behavior (default ordering, extra methods) without changing the schema.

class OrderedArticle(Article):
    class Meta:
        proxy = True
        ordering = ["title"]

Meta Options & Constraints

An inner class Meta holds table-level configuration — ordering, verbose names, indexes, and database constraints.

from django.db import models


class Article(models.Model):
    title = models.CharField(max_length=200)
    slug = models.SlugField()
    published_at = models.DateTimeField()

    class Meta:
        ordering = ["-published_at"]           # newest first by default
        verbose_name = "article"
        verbose_name_plural = "articles"
        indexes = [
            models.Index(fields=["-published_at"]),
            models.Index(fields=["slug"]),
        ]
        constraints = [
            models.UniqueConstraint(
                fields=["slug"], name="unique_article_slug"
            ),
        ]

A CheckConstraint enforces a business rule at the database level:

    class Meta:
        constraints = [
            models.CheckConstraint(
                check=models.Q(price__gte=0),
                name="price_non_negative",
            ),
        ]

Model Methods

Fat models, thin views: put data-related logic on the model where it belongs. This keeps business rules in one place and out of your views and templates.

from django.urls import reverse
from django.utils import timezone


class Article(models.Model):
    title = models.CharField(max_length=200)
    slug = models.SlugField(unique=True)
    content = models.TextField()
    published_at = models.DateTimeField(default=timezone.now)

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        """Canonical URL for this object — used by templates and the admin."""
        return reverse("blog:article_detail", kwargs={"slug": self.slug})

    @property
    def is_recent(self):
        """True if published within the last 7 days."""
        return timezone.now() - self.published_at <= timezone.timedelta(days=7)

    @property
    def word_count(self):
        return len(self.content.split())

A note on managers

The objects attribute on every model is a manager — the entry point for queries (Article.objects.all()). You can add custom managers to encapsulate common queries. Managers and their QuerySets are the focus of the next lesson, so we will only preview them here:

class PublishedManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(status="published")


class Article(models.Model):
    # ... fields ...
    objects = models.Manager()        # the default manager
    published = PublishedManager()    # Article.published.all()

Hands-on Exercise

from django.conf import settings
from django.db import models


class TimeStampedModel(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True


class Category(models.Model):
    name = models.CharField(max_length=100)
    slug = models.SlugField(unique=True)

    class Meta:
        verbose_name_plural = "categories"

    def __str__(self):
        return self.name


class Tag(models.Model):
    name = models.CharField(max_length=50)
    slug = models.SlugField(unique=True)

    def __str__(self):
        return self.name


class Post(TimeStampedModel):
    class Status(models.TextChoices):
        DRAFT = "draft", "Draft"
        PUBLISHED = "published", "Published"

    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    body = models.TextField()
    status = models.CharField(
        max_length=10, choices=Status.choices, default=Status.DRAFT
    )
    category = models.ForeignKey(
        Category, on_delete=models.SET_NULL, null=True,
        related_name="posts",
    )
    author = models.ForeignKey(
        settings.AUTH_USER_MODEL, on_delete=models.CASCADE,
        related_name="posts",
    )
    tags = models.ManyToManyField(Tag, related_name="posts", blank=True)

    class Meta:
        ordering = ["-created_at"]

    def __str__(self):
        return self.title


class Comment(TimeStampedModel):
    post = models.ForeignKey(
        Post, on_delete=models.CASCADE, related_name="comments"
    )
    author_name = models.CharField(max_length=100)
    body = models.TextField()

    def __str__(self):
        return f"Comment by {self.author_name} on {self.post}"

Best Practices

Summary & Quiz

📚 Further Reading

• Django Docs — Models
• Django Docs — Model field reference
• Django Docs — Model Meta options
• Django Docs — Constraints reference

🚀 What's Next?

Your models describe the schema you want. In the next lesson, Database Migrations, you'll learn how Django turns those model definitions into real database tables — and how to evolve the schema safely as your models change.