Introduction
Django’s ORM is designed to abstract and simplify database operations, allowing developers to interact with databases using Python instead of SQL. Every Django model comes with a built-in interface for database queries, known as a manager. Managers are the primary way Django interacts with your data, and understanding them is crucial for writing efficient, maintainable, and reusable code.
Model managers act as the bridge between your database tables and your Python code. By default, every Django model has at least one manager called objects, which provides methods like all(), filter(), get(), and many others. However, you are not limited to using only the default manager. Django allows you to create custom model managers that encapsulate frequently used queries and provide a clean, reusable API for your models.
In this lesson, you will learn what model managers are, how they work, and how to create and use custom managers. You will also explore when to use them, best practices, and how they improve your project’s structure and readability.
Understanding Model Managers
Whenever you define a Django model, Django automatically adds a default manager named objects. This manager is responsible for all database operations related to that model. For example, if you have a model named Book, you can access all book records using:
books = Book.objects.all()
Here, objects is the default manager that returns a QuerySet containing all instances of the Book model. When you call methods like filter() or exclude(), you are using the methods provided by this manager.
Managers are essentially Python classes that inherit from django.db.models.Manager. They provide the interface through which Django interacts with the database. Every time you use Book.objects, you are working through the model’s manager.
The key point is that while Django provides this default manager, you can define your own to extend its behavior. For instance, if your application frequently needs to query only published books or active users, you can define a custom manager that includes methods for these specific operations.
Creating a Custom Model Manager
A custom manager is a subclass of models.Manager. You can define new methods in this subclass to encapsulate common queries, making your code cleaner and more maintainable.
Let’s start with a simple example. Suppose you have a model named Book and you want to frequently retrieve only those books that have a non-null published_date value. Instead of repeating the same filter query in multiple views or functions, you can define a custom manager method.
from django.db import models
class BookManager(models.Manager):
def published_books(self):
return self.filter(published_date__isnull=False)
class Book(models.Model):
title = models.CharField(max_length=100)
published_date = models.DateField(null=True)
objects = BookManager()
In this example, the BookManager class inherits from Django’s base Manager class and defines a new method called published_books. This method returns a QuerySet containing all books that have a published_date.
Now, instead of writing:
Book.objects.filter(published_date__isnull=False)
you can simply write:
Book.objects.published_books()
This approach makes your code much more readable and reusable.
How Custom Managers Work
When Django initializes a model, it automatically attaches the manager instances defined on that model. Each manager instance has access to the model it is attached to, allowing it to query that model’s data.
In our previous example, when you define objects = BookManager(), Django automatically binds the manager to the Book model. This means that whenever you call Book.objects, Django knows to use the BookManager class as the manager for that model.
Under the hood, the manager uses Django’s ORM to generate QuerySets. Each method you define inside a manager should return a QuerySet or data derived from one. This ensures that your custom methods can be chained with other QuerySet methods.
For example:
Book.objects.published_books().order_by('title')
In this line, the published_books() method returns a QuerySet, allowing you to chain the order_by() method afterward.
This chainability is one of Django ORM’s biggest advantages, as it keeps your code clean, efficient, and expressive.
Using Multiple Managers
Django models can have more than one manager. While the first manager defined in the model class becomes the default one, you can define additional managers with different names for different use cases.
For example:
class Book(models.Model):
title = models.CharField(max_length=100)
published_date = models.DateField(null=True)
objects = BookManager()
all_objects = models.Manager()
Here, objects is the custom manager that includes the published_books() method, while all_objects is the default manager that returns all records without any filtering.
You can now call:
Book.objects.published_books() # Custom filtered results
Book.all_objects.all() # Unfiltered results
This pattern is particularly useful when you want to provide both filtered and unfiltered data access within the same model.
Extending the Default Manager
Sometimes, you might not want to replace the default manager entirely. Instead, you may want to extend its functionality. You can do this by subclassing models.Manager and adding your custom methods while retaining access to the existing ones.
For example:
class ExtendedBookManager(models.Manager):
def get_queryset(self):
return super().get_queryset().filter(published_date__isnull=False)
def recent_books(self):
return self.get_queryset().order_by('-published_date')[:5]
In this example, we override the get_queryset() method to return only published books by default. We also add a custom method recent_books() to get the five most recently published books.
You can attach this manager to your model like this:
class Book(models.Model):
title = models.CharField(max_length=100)
published_date = models.DateField(null=True)
objects = ExtendedBookManager()
Now, Book.objects.all() will only return books that have a published date, because the manager’s default QuerySet has been customized. Additionally, you can still use the new recent_books() method.
Overriding get_queryset()
The get_queryset() method is at the core of every manager. It defines the initial QuerySet that a manager returns. By default, it returns all objects in the model’s table. When you override it, you control what data is initially fetched.
For example, you can use it to hide deleted records, restrict visible objects, or add custom filters globally.
class ActiveBookManager(models.Manager):
def get_queryset(self):
return super().get_queryset().filter(is_active=True)
When attached to a model:
class Book(models.Model):
title = models.CharField(max_length=100)
is_active = models.BooleanField(default=True)
objects = ActiveBookManager()
Now, every time you call Book.objects.all(), only active books will be returned. This approach is excellent for implementing soft deletes or visibility restrictions.
Combining Custom Managers and Default Managers
In many real-world scenarios, you may want both filtered and unfiltered data access in your application. To achieve this, you can attach both a custom and a default manager to the same model.
class Book(models.Model):
title = models.CharField(max_length=100)
published_date = models.DateField(null=True)
is_active = models.BooleanField(default=True)
objects = ActiveBookManager()
all_objects = models.Manager()
Here, objects returns only active books, while all_objects gives access to all records, including inactive ones. This structure provides flexibility while maintaining clarity in your code.
Best Practices for Custom Managers
While creating custom managers, there are some best practices you should follow to ensure your code remains maintainable and consistent.
First, always return a QuerySet from your custom manager methods whenever possible. This allows chaining and keeps your methods compatible with Django’s QuerySet API.
Second, keep your custom managers focused. Each custom manager should ideally represent a distinct data access pattern or business rule. Avoid putting unrelated queries in the same manager.
Third, if your manager becomes too large, consider breaking it into smaller parts or creating multiple managers for different purposes.
Fourth, always test your manager methods thoroughly. Because managers directly affect how your application retrieves data, errors here can have widespread effects.
Fifth, document your custom managers. Make sure other developers understand the purpose of each method and when to use it.
Using Built-in Managers
While Django allows you to define custom managers, it also comes with several built-in managers that provide powerful functionality out of the box. The default manager, objects, supports methods like all(), filter(), exclude(), and get().
The all() method returns all objects in the database table:
Book.objects.all()
The filter() method retrieves records that meet specific conditions:
Book.objects.filter(published_date__year=2020)
The exclude() method excludes records that match certain conditions:
Book.objects.exclude(author='J.K. Rowling')
The get() method retrieves a single object that matches a condition:
Book.objects.get(id=1)
These built-in methods are part of Django’s ORM and are accessible through any manager, including your custom ones. This means that your custom managers automatically inherit these methods unless explicitly overridden.
Using Managers with Related Models
Managers can also be useful when dealing with related models. For example, if a model has a foreign key relationship, you can define a custom manager to filter related data.
Consider a Publisher model related to the Book model:
class Publisher(models.Model):
name = models.CharField(max_length=100)
Now modify the Book model to include a foreign key to Publisher:
class Book(models.Model):
title = models.CharField(max_length=100)
publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE)
published_date = models.DateField(null=True)
objects = BookManager()
You can now write queries like:
books = Book.objects.published_books().filter(publisher__name='Penguin')
Here, the custom manager filters the books first, and then you further filter by publisher name.
Real-World Use Cases for Custom Managers
Custom managers are most beneficial when your project requires frequently used or complex queries that you want to encapsulate for reusability. Let’s look at some practical examples.
If you are building an e-commerce platform, you might have a Product model. You can define a custom manager to get all available products:
class ProductManager(models.Manager):
def available(self):
return self.filter(is_available=True)
If you are building a blogging application, you could have a PostManager that retrieves all published posts:
class PostManager(models.Manager):
def published(self):
return self.filter(status='published')
In a social networking site, a UserManager could retrieve all active or verified users:
class UserManager(models.Manager):
def active_users(self):
return self.filter(is_active=True)
These examples demonstrate how custom managers can simplify your views and logic by providing clear, expressive methods.
Chaining Custom Manager Methods
Because custom manager methods return QuerySets, they can be chained with other QuerySet methods. This means you can build complex queries in a readable way.
Example:
books = Book.objects.published_books().order_by('-published_date')
Here, published_books() filters the books, and order_by() sorts them. Django combines both into a single SQL query under the hood, making the process efficient and performant.
Testing Custom Managers
Like any other part of your application, managers should be tested to ensure they work as expected. You can use Django’s testing framework to create test cases for your custom managers.
For example:
from django.test import TestCase
from .models import Book
class BookManagerTest(TestCase):
def setUp(self):
Book.objects.create(title='Book 1', published_date='2020-01-01')
Book.objects.create(title='Book 2', published_date=None)
def test_published_books(self):
published = Book.objects.published_books()
self.assertEqual(published.count(), 1)
This ensures your published_books() method returns only books that have a published date.
Leave a Reply