はじめに
テスト実行時にN+1を例外にしてCIで落とす、という運用をnplusoneというライブラリを使って続けていました。
nplusoneはN+1を検出するために、Djangoの内部メソッドRelatedPopulator.__init__を差し替えているようです。
Djangoを6.1に上げたところ、このメソッドの引数が変わっていたため差し替えた処理と合わなくなり、ValueError: too many values to unpackでテストが全滅しました。
nplusoneの最終リリースは2018年の1.0.0で、Django6.1に対応してくれる見込みはなさそうです。そこで乗り換え先を探しました。
Django6.1、django-zeal2.3.0で試しています。.get()の繰り返し検出は2.1.0で追加された機能です。
乗り換え先の候補を比べてみた
ここでいうeager loadは、select_related / prefetch_relatedで関連先をまとめて取得することを指します。
| 候補 | 未使用eager loadの検出 | 懸念 |
|---|---|---|
| django-zeal | なし | 依存なし・活発にメンテされている・zealのCIにDjango6.1がある |
| nplus1(nplusoneの書き直し) | あり | nplusoneと同じくDjangoの内部メソッドを差し替える方式なので、Djangoの更新でまた壊れると思われる |
| django-debug-toolbar | なし | 手動で確認するツールなのでCIに組み込めない |
nplus1は未使用eager loadを検出できますが、同じ理由でまた壊れるのは避けたかったのでその検出を失うことは承知のうえでdjango-zealを選びました。
検出できる範囲はこう変わった
| パターン | nplusone | django-zeal |
|---|---|---|
| ループ内のリレーション走査 | ✅ | ✅ |
| HTTPを経由しない経路(service直呼び・command) | ❌ | ✅(zeal_context()で包む) |
同じ箇所の.get()繰り返し |
❌ | ✅ |
未使用のselect_related/prefetch_related
|
✅ | ❌ |
nplusoneのころもmiddlewareだけで使っていたので、serviceを直接呼ぶユニットテストやmanagement commandでは検出できていませんでした。
以下、設定から順に書いていきます。
zealは本番に入れない設定
zealはN+1を検出するために、DjangoのORMの処理を差し替えてクエリを追跡します。
ただしINSTALLED_APPSに入れなければ差し替えは行われないので、本番に入れても処理は増えません。
それでも本番では使わないパッケージなので、requirements/test.txtに入れ、有効化もlocal/testのsettingsだけで行うようにしました。
# local/test共通。baseからは読まない
ZEAL_NPLUSONE_THRESHOLD = 2 # 同一クエリ2回で検出。既定値が将来変わっても固定したい
ZEAL_ALLOWLIST = [
# Django標準機能が発行する繰り返しクエリ
{"model": "sessions.Session"},
{"model": "contenttypes.ContentType"},
{"model": "auth.Permission"},
]
from ._zeal import *
INSTALLED_APPS = [*INSTALLED_APPS, "zeal"]
MIDDLEWARE = [*MIDDLEWARE, "zeal.middleware.zeal_middleware"] # 末尾に置く
ZEAL_RAISE = False # 開発中は警告のみ
settings/test.pyも_zealの読み込みとINSTALLED_APPS/MIDDLEWAREへの追加は同じで、違うのはZEAL_RAISEだけです。
from ._zeal import *
INSTALLED_APPS = [*INSTALLED_APPS, "zeal"]
MIDDLEWARE = [*MIDDLEWARE, "zeal.middleware.zeal_middleware"]
ZEAL_RAISE = True # テストでは例外 → CIが落ちる
HTTPを通らない経路でも検出できるようになった
zealのmiddlewareが見ているのはHTTPリクエストだけです。
テストでいえば、テストクライアントを通したリクエストしか検出対象になりません。
zealにはzeal_context()というコンテキストマネージャがあるので、conftestのautouse fixtureでテスト全体を包んで解決しました。
import pytest
from zeal import zeal_context
@pytest.fixture(autouse=True)
def enable_zeal():
with zeal_context():
yield
これで検出の単位は次のようになります。
-
HTTP経路: 1リクエスト(middlewareがリクエストごとに
zeal_context()で包み直すので、カウンタがリセットされる) - それ以外: 1テスト
同じ箇所の.get()繰り返しも拾ってくれるようになった
zealはリレーションの走査(for x in qs: x.related)だけでなく、同じ呼び出し箇所から.get()が繰り返されるパターンも検出します。
# 検出される: ループのたびに同じ箇所から .get() が飛ぶ
for row in rows:
parent = Parent.objects.get(pk=row.parent_id)
移行してCIを回したら、月次バッチの中に「一括ロード済みのオブジェクトを、ループ内で主キーから引き直している」箇所が1件見つかりました。
nplusoneでは見えていなかった冗長なクエリで、オブジェクトを引数で渡すように直して解消しました。
使っていないeager loadには気づけなくなった
nplusoneには「select_relatedしたのに、そのリレーションに一度も触らなかった」ことを警告する機能がありました。
zealのREADMEでも、未使用のprefetchは(まだ)検出しないと明記されています(2026年11月15日現在)。
未使用のeager loadは無駄なJOINになるだけで、動作が壊れるわけではありません。
CIで落ちなくなっても致命的ではないと判断しましたが、「自動で気づける」が「レビューで見るしかない」に変わったので、コーディング規約に明記しました。
ついでに、nplusone向けの抑制コードが本番側に1箇所残っていたのも、この機能ごとなくなったので削除できました。
allowlistとzeal_ignoreの使い分け
ZEAL_ALLOWLISTに足すと、そのモデルの再取得によるN+1はどこで起きても検出されなくなります。
そのため、allowlistに登録するのはアプリ側で解消できないものだけにしました。
1つはセッションやContentType、Permissionのように、Django標準機能が発行する繰り返しクエリです。
もう1つは構造上必要な2回目の.get()で、たとえば2つのトランザクションに分かれた処理が、それぞれselect_for_updateで行ロックを取り直すケースです。
それ以外、たとえば次のようなテスト都合の繰り返しは、その箇所だけをzealのzeal_ignoreで囲んでいます。
from zeal import zeal_ignore
# 検証のための再読込であって、本番コードのN+1ではない
with zeal_ignore([{"model": "users.User", "field": "get()"}]):
for expected in (1, 2, 3):
user.refresh_from_db()
assert user.failed_attempts == expected
囲むのは検証用の再読込だけで、検証対象のservice呼び出しやcall_commandはブロックに入れない、という運用ルールです。
zeal_ignoreは指定したモデル・フィールドだけを抑制し、同じブロック内のリレーション走査は検出し続けます。
範囲さえ広げなければ、本物のN+1は見逃さずに済むと思います。
検出できていること自体もテストにした
autouse fixtureやallowlistが壊れていると、N+1があっても検出されず、他のテストはそのまま通ってしまいます。
そこで「検出できること」を直接テストしました。
Storeはcompanyへの外部キーを持つモデルで、storesはStoreを数件(自分の場合は3件でした)作成するfixtureです。
import pytest
from zeal import NPlusOneError
from stores.models import Store
@pytest.fixture(autouse=True)
def raise_on_n_plus_one(settings):
settings.ZEAL_RAISE = True
def test_detects_relation_n_plus_one_outside_http(stores):
"""HTTP を経由しない経路でも検出する(fixture が壊れたらここが落ちる)"""
with pytest.raises(NPlusOneError, match=r"stores\.Store\.company"):
[store.company.name for store in Store.objects.all()]
def test_no_false_positive_with_select_related(stores):
for store in Store.objects.select_related("company"):
_ = store.company.name
def test_detects_repeated_get(stores):
with pytest.raises(NPlusOneError, match=r"stores\.Store\.get\(\)"):
[Store.objects.get(pk=s.pk) for s in Store.objects.all()]
このテストでは、pytest-djangoのsettings fixtureでZEAL_RAISEをTrueにしています。
こうしておくと、settings/test.pyの値が変わっても、このテストは「N+1を検出できるか」だけを確かめられます。
settings/test.pyのZEAL_RAISE = Trueが消えていないかは、値を読んで確かめる別のテストで見ています。
まとめ
nplusoneのように開発が止まっていて、Djangoの内部メソッドを差し替えているライブラリは、Djangoのアップデートで突然壊れることがあると分かりました。
乗り換え先も同じ方式だと同じことがまた起きると思い、今回はdjango-zealを選びました。
移行したことで、HTTPを経由しない経路や同じ箇所の.get()の繰り返しも検出できるようになりました。
一方で未使用eager loadの検出はなくなったので、そこは規約とレビューで補うことにしました。
また、検出ツールは「検出できていること」自体をテストで確かめておかないと、壊れたときに気づけないと感じました。
今後ほかの検出ツールを入れるときも、同じようにテストを書いておこうと思います。