Django Model Managers
Introduction
When you interact with Django's database layer, you're actually working with model managers behind the scenes. Every time you write MyModel.objects.all() or MyModel.objects.filter(), you're using Django's default model manager, accessible through the objects attribute.
Model managers are the interface through which Django models perform database queries. They act as a bridge between your model class and the database layer, providing methods like get(), filter(), create(), and all().
In this tutorial, we'll explore:
- What model managers are and how they work
- How to use the default manager
- Creating custom managers for specialized queries
- Modifying the base manager
- Practical applications of custom managers
Understanding the Default Manager
Every Django model automatically gets a default manager called objects. This manager provides methods to interact with your database:
# Retrieving all objects
all_users = User.objects.all()
# Filtering objects
active_users = User.objects.filter(is_active=True)
# Getting a single object
user = User.objects.get(id=1)
# Creating a new object
new_user = User.objects.create(username='johndoe', email='[email protected]')
Behind the scenes, the objects manager translates these method calls into SQL queries, executes them against your database, and returns the appropriate results.
Creating Custom Managers
While the default manager is powerful, you can create custom managers to encapsulate common queries and operations. This helps keep your code DRY (Don't Repeat Yourself) and makes your models more readable.
Basic Custom Manager
To create a custom manager, define a class that inherits from models.Manager, then add it as an attribute to your model:
from django.db import models
class ActiveUserManager(models.Manager):
def get_queryset(self):
# Return only active users
return super().get_queryset().filter(is_active=True)
class User(models.Model):
username = models.CharField(max_length=100)
email = models.EmailField()
is_active = models.BooleanField(default=True)
objects = models.Manager() # The default manager
active_objects = ActiveUserManager() # Our custom manager
def __str__(self):
return self.username
With this setup, you can now access only active users directly:
# Get all users (using default manager)
all_users = User.objects.all()
# Get only active users (using custom manager)
active_users = User.active_objects.all() # This already filters by is_active=True
Adding Custom Methods to Managers
You can also add custom methods to your manager to encapsulate specific queries:
from django.db import models
class ProductManager(models.Manager):
def get_queryset(self):
return super().get_queryset()
def in_stock(self):
"""Return products that have stock > 0"""
return self.get_queryset().filter(stock__gt=0)
def out_of_stock(self):
"""Return products with no stock"""
return self.get_queryset().filter(stock=0)
def low_stock(self, threshold=5):
"""Return products with stock below threshold"""
return self.get_queryset().filter(stock__gt=0, stock__lte=threshold)
class Product(models.Model):
name = models.CharField(max_length=100)
price = models.DecimalField(max_digits=10, decimal_places=2)
stock = models.IntegerField(default=0)
objects = ProductManager()
def __str__(self):
return self.name
This allows for very expressive and readable queries:
# Find products in stock
available = Product.objects.in_stock()
# Find out-of-stock products
unavailable = Product.objects.out_of_stock()
# Find products with low stock (custom threshold)
need_restock = Product.objects.low_stock(threshold=3)
Replacing the Default Manager
If you want your custom manager to be the default, simply name it objects:
class ActiveOnlyManager(models.Manager):
def get_queryset(self):
return super().get_queryset().filter(is_active=True)
class User(models.Model):
username = models.CharField(max_length=100)
email = models.EmailField()
is_active = models.BooleanField(default=True)
# Replace the default manager
objects = ActiveOnlyManager()
However, be cautious when doing this! Replacing the default manager can have unexpected consequences:
User.objects.all()will now only return active users- Related models (through foreign keys) will only access active users
- Admin site might behave differently
It's often better to keep the default manager and add custom managers alongside it.
Manager Methods vs. Model Methods
Should you add a method to a manager or to the model itself? Here's a simple guideline:
- Manager methods should handle operations that affect a collection of model instances (querysets)
- Model methods should handle operations on a single instance
For example:
class OrderManager(models.Manager):
# Manager method - operates on collections
def recent_orders(self, days=7):
from datetime import timedelta
from django.utils import timezone
cutoff_date = timezone.now() - timedelta(days=days)
return self.get_queryset().filter(created_at__gte=cutoff_date)
class Order(models.Model):
customer = models.ForeignKey('Customer', on_delete=models.CASCADE)
total = models.DecimalField(max_digits=10, decimal_places=2)
created_at = models.DateTimeField(auto_now_add=True)
objects = OrderManager()
# Model method - operates on a single instance
def is_recent(self, days=7):
from datetime import timedelta
from django.utils import timezone
cutoff_date = timezone.now() - timedelta(days=days)
return self.created_at >= cutoff_date
Usage example:
# Manager method for querying multiple objects
recent_orders = Order.objects.recent_orders(days=3)
# Model method for checking a single instance
order = Order.objects.get(id=1)
if order.is_recent(days=3):
print("This is a recent order")
Real-world Example: Blog Application
Let's see a practical example of managers in a blog application:
from django.db import models
from django.utils import timezone
class PostManager(models.Manager):
def published(self):
"""Return only published posts."""
return self.get_queryset().filter(
status='published',
publish_date__lte=timezone.now()
)
def drafts(self):
"""Return only draft posts."""
return self.get_queryset().filter(status='draft')
def get_by_author(self, username):
"""Return posts by a specific author."""
return self.get_queryset().filter(author__username=username)
def get_by_tag(self, tag):
"""Return posts with a specific tag."""
return self.get_queryset().filter(tags__name=tag).distinct()
class Post(models.Model):
STATUS_CHOICES = (
('draft', 'Draft'),
('published', 'Published'),
)
title = models.CharField(max_length=200)
slug = models.SlugField(max_length=200, unique=True)
content = models.TextField()
author = models.ForeignKey('auth.User', on_delete=models.CASCADE)
publish_date = models.DateTimeField(default=timezone.now)
created_date = models.DateTimeField(auto_now_add=True)
status = models.CharField(max_length=10, choices=STATUS_CHOICES, default='draft')
tags = models.ManyToManyField('Tag', blank=True)
# Add both the default manager and our custom manager
objects = models.Manager() # Default manager
posts = PostManager() # Custom manager
class Meta:
ordering = ('-publish_date',)
def __str__(self):
return self.title
Using our custom manager in views:
# views.py
from django.shortcuts import render
from .models import Post
def home_view(request):
# Only show published posts on the homepage
published_posts = Post.posts.published()
return render(request, 'blog/home.html', {'posts': published_posts})
def author_posts_view(request, username):
# Show posts by a specific author
author_posts = Post.posts.get_by_author(username).published()
return render(request, 'blog/author.html', {'posts': author_posts, 'author': username})
def tag_view(request, tag):
# Show posts with a specific tag
tagged_posts = Post.posts.get_by_tag(tag).published()
return render(request, 'blog/tag.html', {'posts': tagged_posts, 'tag': tag})
def dashboard_view(request):
# For an admin dashboard, show draft posts too
draft_posts = Post.posts.drafts()
return render(request, 'blog/dashboard.html', {'drafts': draft_posts})
Using Multiple Managers with Inheritance
When you use model inheritance in Django, manager inheritance follows specific rules:
- If no managers are declared in a child model, it inherits the managers from its parent.
- If you declare managers in a child model, it replaces all the managers from the parent.
Here's an example:
class BaseModel(models.Model):
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
# Base model managers
objects = models.Manager()
class Meta:
abstract = True
class SpecialProduct(BaseModel):
name = models.CharField(max_length=100)
price = models.DecimalField(max_digits=10, decimal_places=2)
is_special = models.BooleanField(default=True)
# This model inherits the 'objects' manager from BaseModel
# But we can add additional managers
special_objects = models.Manager()
def __str__(self):
return self.name
Summary
Django model managers are powerful tools that help you organize and encapsulate database query logic. They provide a clean way to:
- Define reusable query methods
- Limit query results by default conditions
- Separate different types of queries into logical groups
- Keep your views and business logic cleaner
Best practices for using model managers:
- Keep the default
objectsmanager unless you have a very good reason not to - Use method names that clearly describe what the query does
- Add custom managers to encapsulate complex or frequently used queries
- Use manager methods for operations on querysets and model methods for operations on instances
Exercises
-
Create a custom manager for a
Bookmodel that provides methods for:- Finding books published in a specific year
- Finding books by a specific author
- Finding books with rating above a certain threshold
-
Extend the blog example by adding a manager method that returns posts that are trending (based on view count or comments).
-
Create a
SoftDeletionManagerthat automatically excludes objects marked as deleted (has_deleted=True) from all queries.
Additional Resources
- Django Documentation on Managers
- Django ORM Cookbook - Custom Managers
- Two Scoops of Django - Has an excellent chapter on managers
By leveraging model managers effectively, you can make your Django code more maintainable, readable, and consistent. They're a great example of Django's "fat models, thin views" philosophy in action!
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)