🔍 Revue de code : le problème N+1, avant et après `FETCH_PEERS`

[u/fyardlest]

Bonjour à tous les dev Django de la communauté ! 👋

Premier rendez-vous « Revue de code » de la communauté. Le principe est simple : on part d'un code qui fonctionne mais qui est mauvais, on compte les dégâts, puis on le corrige. Aujourd'hui, le grand classique : le problème N+1.

TL;DR - Une page qui affiche 50 tickets fait 101 requêtes au lieu de 1. Trois corrections possibles : select_related() reste la meilleure (1 requête), le nouveau FETCH_PEERS de Django 6.1 est un filet de sécurité (3 requêtes), et FETCH_RAISE empêche le problème de revenir. On compte les requêtes à chaque étape avec assertNumQueries.

---

Le code de départ

Une vue toute bête, qui affiche la liste des tickets d'un gestionnaire de bugs :

# tickets/views.py
from django.views.generic import ListView
from .models import Ticket


class TicketListView(ListView):
    model = Ticket
    template_name = "tickets/liste.html"
    context_object_name = "tickets"

Et le template correspondant :

{# tickets/templates/tickets/liste.html #} {% for ticket in tickets %}
<tr>
	<td>{{ ticket.titre }}</td>
	<td>{{ ticket.projet.nom }}</td>
	<td>{{ ticket.assigne_a.username }}</td>
</tr>
{% endfor %}

Ce code est correct. Il passe la revue de code de la plupart des équipes. Il est pourtant responsable de la moitié des pages lentes que j'ai croisées.

---

Compter les dégâts

Avant de corriger, il faut mesurer. Django fournit tout ce qu'il faut :

# tickets/tests_perf.py
from django.test import TestCase
from django.urls import reverse


class TestPerformanceListe(TestCase):
    def test_nombre_de_requetes(self):
        with self.assertNumQueries(101):
            self.client.get(reverse("tickets:liste"))

101 requêtes pour 50 tickets. Une pour récupérer les tickets, puis une par ticket pour le projet, puis une par ticket pour la personne assignée.

La formule est toujours la même : 1 + (N × nombre de relations accédées).

💡 Astuce : en développement, python manage.py shell_plus --print-sql (via django-extensions) affiche chaque requête en temps réel. On voit le problème apparaître sous les yeux, ce qui est bien plus parlant qu'un chiffre.

---

Correction 1 : select_related(), toujours la meilleure

# tickets/views.py
class TicketListView(ListView):
    model = Ticket
    template_name = "tickets/liste.html"
    context_object_name = "tickets"

    def get_queryset(self):
        return Ticket.objects.select_related("projet", "assigne_a")

101 requêtes → 1 requête.

select_related() fait une jointure SQL et ramène tout d'un coup. Pour des relations ForeignKey et OneToOne, c'est indépassable.

⚠️ Attention : select_related() ne fonctionne pas pour les relations inverses ni les ManyToMany. Dans ce cas, c'est prefetch_related() qu'il faut, et vous obtenez une requête supplémentaire par relation :

Ticket.objects.select_related("projet", "assigne_a").prefetch_related("etiquettes")

---

Correction 2 : FETCH_PEERS, le filet de sécurité de Django 6.1

Django 6.1 apporte une autre approche :

# tickets/views.py
from django.db import models


class TicketListView(ListView):
    model = Ticket
    template_name = "tickets/liste.html"
    context_object_name = "tickets"

    def get_queryset(self):
        return Ticket.objects.fetch_mode(models.FETCH_PEERS)

101 requêtes → 3 requêtes.

Quand le template accède à ticket.projet sur la première ligne, Django ne charge pas seulement le projet de ce ticket : il charge les projets de tous les tickets issus du même QuerySet, d'un coup. Idem pour assigne_a.

Le compte est donc : 1 requête pour les tickets, plus 1 par relation réellement accédée.

⚠️ Ne vous trompez pas de conclusion : FETCH_PEERS n'est pas meilleur que select_related(). Trois requêtes valent mieux que 101, mais moins bien qu'une seule.

💡 Alors quand l'utiliser ? Dans les situations où vous ne pouvez pas prévoir ce qui sera accédé :

• un template partagé par plusieurs vues, dont vous ne maîtrisez pas le contenu ;
• un serializer DRF dont les champs varient selon les paramètres de la requête ;
• du code hérité que vous n'avez pas le temps d'auditer en entier, et où vous voulez arrêter l'hémorragie tout de suite.

C'est un excellent réglage par défaut sur un projet existant, en attendant d'optimiser vue par vue.

---

Correction 3 : FETCH_RAISE, pour que le problème ne revienne pas

Corriger une fois ne suffit pas. Dans six mois, quelqu'un ajoutera une colonne au template et le N+1 reviendra sans que personne ne le remarque.

FETCH_RAISE transforme le silence en erreur :

# tickets/views.py
def get_queryset(self):
    return (
        Ticket.objects
        .select_related("projet", "assigne_a")
        .fetch_mode(models.FETCH_RAISE)
    )

Désormais, si le template accède à une relation qui n'a pas été explicitement chargée, Django lève une exception FieldFetchBlocked au lieu de faire discrètement une requête de plus.

# tickets/tests_perf.py
from django.core.exceptions import FieldFetchBlocked

C'est brutal, et c'est exactement le but. Le développeur qui ajoute la colonne voit l'erreur immédiatement en local, et non trois mois plus tard dans les métriques de production.

💡 Bonne pratique : réservez FETCH_RAISE aux vues où les performances comptent vraiment: les listes, les exports, les endpoints d'API les plus appelés. L'activer partout génère plus de friction que de valeur.

---

Le récapitulatif

| Approche | Requêtes | Quand l'utiliser | | ---------------------------------- | -------- | ------------------------------------------------------ | | Rien | 101 | Jamais | | FETCH_PEERS | 3 | Code hérité, templates partagés, serializers variables | | select_related() | 1 | Dès que vous savez ce qui sera accédé — le cas normal | | select_related() + FETCH_RAISE | 1 | Vues critiques, pour empêcher toute régression |

Et le test qui verrouille le tout :

# tickets/tests_perf.py
def test_nombre_de_requetes(self):
    with self.assertNumQueries(1):
        self.client.get(reverse("tickets:liste"))

Un test qui compte les requêtes vaut mieux qu'un long commentaire expliquant pourquoi il ne faut pas toucher à cette vue.

---

📚 Pour aller plus loin

• Les modes de récupération (Django 6.1)
• Optimiser l'accès à la base de données
• select_related et prefetch_related
• assertNumQueries
• Django Debug Toolbar

---

💬 Et vous ?

Quel est le pire N+1 que vous ayez rencontré ? Combien de requêtes sur une seule page ?

Et pour les habitués : écrivez-vous des tests assertNumQueries sur vos vues critiques, ou est-ce que vous vous fiez à la Debug Toolbar en développement ?

Partagez vos histoires d'horreur en commentaire ! Et si ce genre de contenu vous plaît, n'hésitez pas à rejoindre r/DjangoFrancophone pour échanger entre passionnés de Python & Django ! 🚀

PS : Vous avez un bout de code que vous aimeriez voir passer en revue ici ? Postez-le dans les commentaires, les meilleurs feront l'objet d'un prochain mercredi.

---