"What does on_delete=models.CASCADE mean?"

"CASCADE means when the parent object is deleted, all related child objects are automatically deleted too. Other options: PROTECT (prevent deletion), SET_NULL (set FK to null), SET_DEFAULT (set to default value), DO_NOTHING (leave orphaned records)."

"How do I query related objects in Django?"

"Forward: comment.post gives the related Post. Reverse: post.comments.all() gives all Comments for a Post (using related_name). Without related_name, use post.comment_set.all() (Django's default reverse manager name)."

Django One-to-Many Relationships: ForeignKey Complete Guide

Q: "How do I create a one-to-many relationship in Django?"

"Use ForeignKey in the 'many' side model. Example: class Comment(models.Model): post = models.ForeignKey(Post, on_delete=models.CASCADE, related_name='comments'). Each Comment belongs to one Post; each Post can have many Comments."

A one-to-many relationship in Django is one of the most common database patterns you will encounter when building web applications. It describes a situation where a single record in one table is associated with multiple records in another table. Django implements this relationship through the ForeignKey field, making it straightforward to define, query, and manage related objects across your models.

In this guide, we will cover everything you need to know about Django one-to-many relationships: from defining ForeignKey fields in your models, understanding on_delete behaviors, querying related objects in both directions, and applying these concepts in a real-world blog example.

What Is a One-to-Many Relationship?

A one-to-many relationship (also called a many-to-one relationship depending on which side you look at) means that one record in a parent table can be linked to many records in a child table, but each child record belongs to exactly one parent.

Real-world examples include:

A blog post has many comments, but each comment belongs to one post.
An author writes many books, but each book has one author.
A department contains many employees, but each employee belongs to one department.
A category contains many products, but each product belongs to one category.

In relational database terms, the “many” side holds a foreign key column that references the primary key of the “one” side. Django abstracts this with the ForeignKey model field.

It is worth noting the difference between a one-to-many relationship and a Django one-to-one relationship. In a one-to-one relationship, each record on both sides is linked to exactly one record on the other side (implemented with OneToOneField). In a one-to-many relationship, the parent side can have multiple children.

Defining ForeignKey in Django Models

To create a one-to-many relationship in Django, you add a ForeignKey field to the model on the “many” side. Here is a basic example:

from django.db import models


class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title


class Comment(models.Model):
    post = models.ForeignKey(
        Post,
        on_delete=models.CASCADE,
        related_name='comments'
    )
    author_name = models.CharField(max_length=100)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

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

Key points about this definition:

The ForeignKey is placed on the Comment model (the “many” side).
The first argument is the related model (Post).
on_delete=models.CASCADE specifies what happens when the parent is deleted.
related_name='comments' defines the reverse accessor name on the Post model.

The related_name parameter is optional but highly recommended. Without it, Django creates a default reverse manager named comment_set (lowercase model name + _set). Using an explicit related_name makes your code more readable and self-documenting.

If you have multiple ForeignKey fields pointing to the same model, you must specify different related_name values to avoid naming conflicts:

class Transfer(models.Model):
    from_account = models.ForeignKey(
        Account,
        on_delete=models.CASCADE,
        related_name='outgoing_transfers'
    )
    to_account = models.ForeignKey(
        Account,
        on_delete=models.CASCADE,
        related_name='incoming_transfers'
    )
    amount = models.DecimalField(max_digits=10, decimal_places=2)

on_delete Options Explained

The on_delete parameter is required for every ForeignKey field. It tells Django what to do with child records when the referenced parent object is deleted. Here are all available options:

Option	Behavior
`CASCADE`	Delete all child objects when the parent is deleted. Most common choice.
`PROTECT`	Prevent deletion of the parent if child objects exist. Raises `ProtectedError`.
`SET_NULL`	Set the foreign key to `NULL` (requires `null=True` on the field).
`SET_DEFAULT`	Set the foreign key to its default value (requires `default` to be defined).
`SET(...)`	Set the foreign key to the value passed to `SET()`, or call a callable.
`DO_NOTHING`	Take no action. May cause database integrity errors if not handled at the DB level.
`RESTRICT`	Similar to PROTECT but allows deletion in some CASCADE scenarios (Django 3.1+).

Choosing the right option depends on your business logic:

# CASCADE: Comments are deleted when the post is deleted
class Comment(models.Model):
    post = models.ForeignKey(Post, on_delete=models.CASCADE)

# PROTECT: Cannot delete a category if products exist in it
class Product(models.Model):
    category = models.ForeignKey(Category, on_delete=models.PROTECT)

# SET_NULL: Keep the order but set customer to NULL if customer is deleted
class Order(models.Model):
    customer = models.ForeignKey(
        Customer,
        on_delete=models.SET_NULL,
        null=True,
        blank=True
    )

# SET_DEFAULT: Reassign to a default author
class Article(models.Model):
    author = models.ForeignKey(
        User,
        on_delete=models.SET_DEFAULT,
        default=1  # ID of a "deleted user" placeholder
    )

Django provides intuitive ways to traverse one-to-many relationships in both directions.

Forward Query (Child to Parent)

Accessing the parent from a child instance is straightforward – just access the ForeignKey field attribute:

# Get a comment and access its parent post
comment = Comment.objects.get(pk=1)
post = comment.post  # Returns the related Post instance
print(post.title)

You can also filter child objects by parent attributes using double-underscore notation:

# Get all comments on posts published in 2024
comments = Comment.objects.filter(post__created_at__year=2024)

# Get all comments on posts with "Django" in the title
comments = Comment.objects.filter(post__title__icontains="Django")

Reverse Query (Parent to Children)

To access all children from a parent instance, use the related_name (or the default _set manager):

# Get a post and access all its comments
post = Post.objects.get(pk=1)

# Using related_name='comments'
all_comments = post.comments.all()

# Without related_name, Django uses the default manager
# all_comments = post.comment_set.all()

# Filter comments on this post
recent_comments = post.comments.filter(
    created_at__year=2024
).order_by('-created_at')

# Count comments
comment_count = post.comments.count()

Using select_related and prefetch_related

For performance optimization, Django provides two methods to reduce database queries:

# select_related: Use for forward ForeignKey lookups (JOIN)
comments = Comment.objects.select_related('post').all()
for comment in comments:
    # No additional query needed -- post is already loaded
    print(comment.post.title)

# prefetch_related: Use for reverse (one-to-many) lookups
posts = Post.objects.prefetch_related('comments').all()
for post in posts:
    # No additional query needed -- comments are pre-fetched
    print(post.comments.count())

Use select_related for forward ForeignKey relationships (it performs a SQL JOIN). Use prefetch_related for reverse relationships and many-to-many fields (it performs a separate query and joins in Python).

Practical Example: Blog Posts and Comments

Let us build a more complete example that demonstrates creating, querying, and managing one-to-many relationships in a blog application.

Model Definition

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


class Post(models.Model):
    author = models.ForeignKey(
        User,
        on_delete=models.CASCADE,
        related_name='posts'
    )
    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    content = models.TextField()
    published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ['-created_at']

    def __str__(self):
        return self.title


class Comment(models.Model):
    post = models.ForeignKey(
        Post,
        on_delete=models.CASCADE,
        related_name='comments'
    )
    author_name = models.CharField(max_length=100)
    email = models.EmailField()
    body = models.TextField()
    approved = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ['created_at']

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

# Create a post
post = Post.objects.create(
    author=user,
    title="Django One-to-Many Relationships",
    slug="django-one-to-many",
    content="A comprehensive guide...",
    published=True
)

# Create comments for the post
Comment.objects.create(
    post=post,
    author_name="Alice",
    email="alice@example.com",
    body="Great tutorial!",
    approved=True
)

Comment.objects.create(
    post=post,
    author_name="Bob",
    email="bob@example.com",
    body="Very helpful, thanks!",
    approved=True
)

# You can also use the reverse manager to create
post.comments.create(
    author_name="Charlie",
    email="charlie@example.com",
    body="Can you cover many-to-many next?"
)

Querying in Views

from django.shortcuts import get_object_or_404


def post_detail(request, slug):
    # Efficiently load the post and prefetch approved comments
    post = get_object_or_404(
        Post.objects.prefetch_related('comments'),
        slug=slug,
        published=True
    )
    approved_comments = post.comments.filter(approved=True)

    return render(request, 'blog/post_detail.html', {
        'post': post,
        'comments': approved_comments,
    })

from django.db.models import Count, Q

# Get posts with their comment count
posts_with_counts = Post.objects.annotate(
    total_comments=Count('comments'),
    approved_comments=Count(
        'comments',
        filter=Q(comments__approved=True)
    )
)

for post in posts_with_counts:
    print(f"{post.title}: {post.approved_comments} approved comments")

Common Patterns and Tips

Here are practical patterns and tips for working with Django one-to-many relationships effectively:

1. Use related_name Consistently

Always define related_name explicitly. It serves as documentation and prevents confusion when models have multiple foreign keys to the same parent:

# Good: explicit and descriptive
post = models.ForeignKey(Post, on_delete=models.CASCADE, related_name='comments')

# Avoid: relying on default _set naming
post = models.ForeignKey(Post, on_delete=models.CASCADE)

2. Limit Reverse Querysets with Custom Managers

If you frequently need filtered subsets of related objects, consider adding methods:

class CommentManager(models.Manager):
    def approved(self):
        return self.filter(approved=True)


class Comment(models.Model):
    objects = CommentManager()
    # ... fields ...

3. Use bulk_create for Performance

When inserting many related objects at once, use bulk_create to minimize database queries:

comments = [
    Comment(post=post, author_name=f"User {i}", body=f"Comment {i}")
    for i in range(100)
]
Comment.objects.bulk_create(comments)

4. Handle Circular Imports with String References

If your models are in different apps, use a string reference instead of importing the model directly:

class Comment(models.Model):
    post = models.ForeignKey(
        'blog.Post',  # String reference: 'app_label.ModelName'
        on_delete=models.CASCADE,
        related_name='comments'
    )

5. Index Foreign Key Fields

Django automatically creates a database index on ForeignKey fields, so you do not need to add db_index=True manually. However, if you frequently filter by a combination of the foreign key and another field, consider a composite index:

class Comment(models.Model):
    post = models.ForeignKey(Post, on_delete=models.CASCADE)
    approved = models.BooleanField(default=False)

    class Meta:
        indexes = [
            models.Index(fields=['post', 'approved']),
        ]

6. Avoid N+1 Query Problems

Always use select_related (for forward lookups) or prefetch_related (for reverse lookups) when you know you will access related objects in a loop. This is one of the most common performance pitfalls in Django applications.

By following these patterns, you can build efficient, maintainable Django applications that properly leverage one-to-many relationships through ForeignKey fields.