django-fetch-guard

Prevent Django N+1 queries and accidental lazy database fetches—with explicit contracts or automatic batching.

django-fetch-guard gives Django querysets an explicit fetch policy. Use peers to collapse common N+1 patterns into batched queries, or use strict to fail immediately when code touches a field or relation that was not loaded intentionally.

It uses Django 6.1's native fetch modes when available and provides a carefully scoped compatibility engine for Django 4.2 through 6.0.

Why this exists

This innocent loop can perform 101 queries for 100 books:

books = Book.objects.all()  # 1 query

for book in books:
    print(book.author.name)  # N more queries

Fetch guard lets the queryset state its contract:

# Batch related authors: usually 2 queries in total.
books = Book.objects.fetch_peers()

# Or require an explicit plan: 1 joined query, no hidden fetching allowed.
books = Book.objects.select_related("author").strict()

That contract follows the queryset into serializers, views, templates, and service functions instead of relying on every caller to remember a query-count assertion.

Compatibility

The public API is the same across supported versions. See the compatibility guide for exact differences and honest limitations.

Installation

Install the package from PyPI:

python -m pip install django-fetch-guard

For Django REST Framework integration:

python -m pip install "django-fetch-guard[drf]"

Install the current development version directly from GitHub:

python -m pip install "django-fetch-guard @ git+https://github.com/yassinbahri/django-fetch-guard.git"

Contributors should use the editable setup in CONTRIBUTING.md.

Five-minute setup

1. Add the mixin and manager

from django.db import models
from fetch_guard import FetchGuardModelMixin, GuardedManager


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


class Book(FetchGuardModelMixin, models.Model):
    title = models.CharField(max_length=150)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

    objects = GuardedManager(default_mode="raise")

The mixin is needed only by the Django 4.2–6.0 strict compatibility engine, but keeping it makes the model portable. It adds no database fields and requires no migration.

2. Choose a mode

Book.objects.strict()       # Block an unloaded field or relation.
Book.objects.fetch_peers()  # Batch missing direct relations.
Book.objects.normal()       # Restore traditional lazy loading.

Use explicit relations for consistent eager behavior on every version:

Book.objects.fetch_peers("author")

3. Make strict querysets complete

books = Book.objects.select_related("author").strict()

for book in books:
    print(book.author.name)  # Already loaded; no extra query.

Without select_related("author"), the relation access raises the portable exception:

from fetch_guard import FieldFetchBlocked

Import this package exception rather than Django's exception directly. It maps to Django's native class on 6.1 and the compatibility class on older versions.

Project-wide defaults and checks

Add the application when you want settings validation:

INSTALLED_APPS = [
    # ...
    "fetch_guard",
]

FETCH_GUARD = {
    "DEFAULT_MODE": "raise",
}

Then the manager can inherit the project setting:

objects = GuardedManager()

Validate it with:

python manage.py check --tag fetch_guard

Guard any queryset

An existing manager can remain unchanged:

from fetch_guard import guard_queryset

books = guard_queryset(Book.objects.filter(is_published=True), "raise")

For custom manager/queryset composition, see the getting-started guide.

Django REST Framework

from fetch_guard.drf import FetchGuardMixin
from rest_framework.viewsets import ModelViewSet


class BookViewSet(FetchGuardMixin, ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer
    fetch_guard = {
        "list": "peers",
        "retrieve": "raise",
        "default": "raise",
    }

    def get_queryset(self):
        queryset = super().get_queryset()
        if self.action == "retrieve":
            queryset = queryset.select_related("author")
        return queryset

Read the DRF guide for resolution order, opt-outs, nested serializers, and queryset planning.

Pytest

The package registers a focused fixture:

import pytest
from fetch_guard import FieldFetchBlocked


@pytest.mark.django_db
def test_book_serializer(fetch_guard):
    book = fetch_guard.strict(Book.objects.all()).first()

    with pytest.raises(FieldFetchBlocked):
        serialize_book(book)

The fixture affects only the queryset passed to it; it does not monkey-patch Django globally. See the testing guide.

Verified integration behavior

The test suite includes a minimal Django application and real HTTP server coverage. It measures the same serialization path under every policy:

Run all unit and integration tests with:

python -m pip install -e ".[test]"
python -m pytest

Benchmark

Run the reproducible N+1 benchmark locally with:

python benchmarks/n_plus_one.py

Documentation

• Getting started and core API
• API reference
• Django compatibility and limitations
• Django REST Framework
• Django Ninja
• Django admin
• Hidden fetch examples gallery
• Testing
• Troubleshooting
• Contributing
• Code of Conduct
• Changelog

Current status

0.1.0 is the initial alpha release. The core API, legacy compatibility engine, DRF mixin, pytest fixture, system check, and cross-version CI matrix are implemented. The tests include Django's request client and a live HTTP server. Rich call-site diagnostics and production audit sampling are planned for later releases.

License

MIT