Python Django Foreign Key, One-to-One, and Many-to-Many
Learn how to model many-to-one, one-to-one, and many-to-many relationships in Django with ForeignKey, OneToOneField, and ManyToManyField.

Modeling relationships between records is a core part of designing Django applications. The ForeignKey, OneToOneField, and ManyToManyField fields cover the standard relationship patterns: many-to-one, one-to-one, and many-to-many. This article explains how each field behaves in the database and the ORM, with examples you can use when designing your models.
ForeignKey: Modeling Many-to-One Relationships
A ForeignKey creates a many-to-one relationship. In a typical blog, each Post belongs to a single Author, while an author can write many posts. The field is placed on the model that holds the foreign key, which is the many side of the relationship.
from django.db import models
class Author(models.Model):
name = models.CharField(max_length=100)
class Post(models.Model):
title = models.CharField(max_length=200)
author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='posts')The on_delete parameter controls what happens when the referenced object is deleted. CASCADE deletes the related objects as well, which is common for dependent data. Other options like PROTECT or SET_NULL are useful when you need to preserve the child records or keep them without a parent.
The related_name defines the reverse accessor. Without it, Django uses post_set by default. With related_name='posts', you can access author.posts.all() to get all posts written by that author. Choosing a clear related_name improves readability and avoids collisions when multiple foreign keys point to the same model.
OneToOneField: Extending a Model with a Single Related Record
A OneToOneField is conceptually a ForeignKey with unique=True, but the reverse access returns a single object instead of a queryset. It is typically used to extend a model with additional information that is not always present. A common example is a User and a Profile.
from django.contrib.auth.models import User
class Profile(models.Model):
user = models.OneToOneField(User, on_delete=models.CASCADE)
bio = models.TextField(blank=True)Accessing the profile from a user is straightforward: user.profile. If the profile does not exist, Django raises a RelatedObjectDoesNotExist exception. The forward access from profile to user is profile.user. Because the relationship is one-to-one, you do not need a related_name unless you want to override the default; the default is the lowercase model name.
One-to-one relationships are useful when you want to split a large model into logical parts, or when you need to attach data that is only relevant to a subset of records. They also enforce strict cardinality at the database level with a unique constraint on the foreign key column.
ManyToManyField: Modeling Many-to-Many Relationships
A ManyToManyField expresses a relationship where both sides can have multiple related records. For example, a Student can enroll in many courses, and a Course can have many students. Django creates an intermediary join table automatically.
class Student(models.Model):
name = models.CharField(max_length=100)
class Course(models.Model):
title = models.CharField(max_length=200)
students = models.ManyToManyField(Student, related_name='courses')You can add relationships using course.students.add(student) or student.courses.add(course). The reverse accessor student.courses.all() returns all courses for that student. If the relationship itself needs extra data, such as the enrollment date or grade, you can use a through model:
class Enrollment(models.Model):
student = models.ForeignKey(Student, on_delete=models.CASCADE)
course = models.ForeignKey(Course, on_delete=models.CASCADE)
date_enrolled = models.DateField(auto_now_add=True)
grade = models.CharField(max_length=2, blank=True)
class Course(models.Model):
# ...
students = models.ManyToManyField(Student, through='Enrollment')When you use a through model with required extra fields, you usually need to create the intermediate records explicitly, for example with Enrollment.objects.create(...). This gives you full control over the relationship data instead of relying on the default add() shortcut.
Choosing Between OneToOneField and ForeignKey with unique=True
Since OneToOneField is essentially a ForeignKey with unique=True, the main difference is the reverse access behavior. With a ForeignKey(unique=True), the reverse side returns a queryset (even though it will contain at most one object), while OneToOneField returns a single object directly. This affects how you write code and how you handle missing objects.
Use OneToOneField when you are extending an existing model and want a direct, single-object accessor. Use ForeignKey(unique=True) when you want to keep the reverse relationship as a queryset, perhaps because you might later change the uniqueness constraint, or when you need to use the related manager's methods like filter() on the reverse side. In practice, OneToOneField is the clearer choice for the profile pattern because it signals intent and simplifies access.
Querying and Accessing Related Objects
Django's ORM provides several ways to access related objects. Forward access is straightforward: post.author returns the author. Reverse access uses the related_name or the default manager. For performance, you should avoid the N+1 query problem by using select_related for forward foreign keys and prefetch_related for reverse foreign keys and many-to-many relationships.
# Forward FK: select_related
post = Post.objects.select_related('author').get(pk=1)
print(post.author.name)
# Many-to-many: prefetch_related
student = Student.objects.prefetch_related('courses').get(pk=1)
for course in student.courses.all():
print(course.title)select_related performs a SQL JOIN and retrieves the related object in the same query. prefetch_related runs a separate query for the related objects and caches them, which is better for many-to-many and reverse foreign keys where a JOIN would produce duplicate rows. Use select_related when you know you will access a forward foreign key, and prefetch_related when you need to iterate over a reverse relation or a many-to-many set.
Migrations and Database Schema Implications
When you run makemigrations, Django generates migrations that create the appropriate database schema. A ForeignKey creates a column with a foreign key constraint and an index on that column. A OneToOneField adds a unique constraint on the foreign key column, enforcing the one-to-one cardinality. A ManyToManyField creates an intermediary table with two foreign key columns, each indexed, and a unique constraint on the pair of columns by default.
Understanding these schema details helps you reason about performance and integrity. For large tables, the automatic indexes on foreign keys are usually sufficient, but you can add extra db_index or Meta.indexes options for complex queries. When using a through model, you are responsible for defining indexes and constraints on extra fields if needed.
Common Pitfalls and Production Considerations
One common pitfall is related_name collisions. If two foreign keys in the same model point to the same target model, you must provide distinct related_name values. For example, a Comment model with both author and editor foreign keys to User requires related_name='authored_comments' and related_name='edited_comments' to avoid clashes.
Another issue is circular imports when models reference each other. Use string references for the target model, like 'app.Model', to avoid import-time errors. For self-referential many-to-many relationships, set symmetrical=False if the relationship is not symmetric, such as a follow relationship between users.
In production, be mindful of bulk operations. Calling add(), remove(), or set() on a many-to-many relationship can issue many individual queries, so for large dataset loads consider creating through-model records with bulk_create() instead of many separate calls. Also remember that select_related and prefetch_related only apply to the queryset you call them on; fetching the same records later will need its own eager loading.
Finally, be cautious with on_delete behavior. CASCADE is convenient but can delete large amounts of data unintentionally. PROTECT raises a ProtectedError if deletion would break references, which is safer for important records. SET_NULL requires the foreign key to be nullable. Choose the option that matches your data integrity requirements.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.