Comparison with other tools#

This page compares pytest-queryguard with other tools that look for N+1 queries or count queries. It is written by the author of pytest-queryguard, so read it with that in mind: the matrix is built from the competitors' own documentation and from running their packages, every cell says which, and the measurements are ones I ran myself, on scenarios I wrote.

• Facts about other tools were read on 2026-10-12 and re-checked on 2026-10-13: no tool had a newer release on PyPI since, the tools with a public repository had no new commit on its default branch (fastapi-nplusone and pytest-capquery list none on PyPI), and the cells below that changed say so.
• pytest-queryguard: the measurements were made on the next branch at commit b64d19c, before 0.4.0rc1. The releases on PyPI are now 0.4.0rc4 (a release candidate, 2026-10-12) and the stable 0.3.0 (2026-10-11); the matrix describes 0.4.0rc4. 0.3.0 has no baseline, SARIF, ignore patterns, timing, column-load or write-loop rules and no SQLite or MySQL index check.
• Marks in the matrix: (v) verified by running the package or reading its installed source on that date; (r) read in the package's PyPI description only, not run. Anything I could not check is marked as such.

Who is who#

Release dates come from the PyPI JSON API on 2026-10-12, re-checked on 2026-10-13. Most of these projects are young: pytest-queryguard, queryspy and pytest-querycount shipped their first release in the last three months, so expect all of them to change. This table will be out of date; check the projects' own pages.

pytest-capquery's PyPI metadata has no license field. Its README badge and the LICENSE file in its GitHub repository are Creative Commons Attribution-NonCommercial-ShareAlike 4.0, which is not an open-source license and restricts commercial use. Read it before you adopt it.

Feature matrix#

"not stated" means I did not find a statement in the README, not that it does not work.

Where the others are ahead#

• In your running application. queryspy ships ASGI and WSGI middleware and an optional request panel (modules queryspy.asgi, queryspy.wsgi are in the installed package), and fastapi-nplusone is a FastAPI middleware. nplusone and django-zeal run inside Django, Flask and WSGI apps. pytest-queryguard only runs in tests: its collector is one per process, not one per request.
• Other databases and drivers in their test matrix. The queryspy README says it is tested against SQLite, PostgreSQL and MySQL with psycopg, asyncpg, pymysql, aiomysql and aiosqlite. pytest-queryguard's CI uses SQLite, and PostgreSQL 14 to 18 through pg8000 and asyncpg; psycopg is not in CI (see the FAQ).
• Django. django-zeal and nplusone cover Django; pytest-queryguard does not.
• Writing budgets for you. pytest-querycount --querycount-write-budgets edits your tests to add an exact max_queries marker to each, and --querycount-max applies one budget to every test. pytest-queryguard has a baseline instead, which records findings, not budgets.
• Exact SQL assertions and snapshots. pytest-capquery asserts the exact statements and transaction events of a block and keeps .sql snapshots; pytest-queryguard looks for patterns and does not assert exact SQL.
• A with block to ignore findings. queryspy has an ignore() block; here you use a marker, an ini pattern or a baseline.
• A missing-index check exists elsewhere too. pytest-querycount has its own PostgreSQL check, based on the same idea (plan with sequential scans disabled); pytest-queryguard is not alone in having one.
• Maturity. The projects here are all young. nplusone has been around longest, but has not had a release since 2018.

What I measured#

N+1 and budgets on SQLite#

A larger run, with 143 scenarios and precision and recall per finding kind, is on the accuracy page.

I ran 45 scenarios in tests/scenarios (SQLAlchemy ORM and Core, sync and async, SQLite) against three packages, each in its own virtual environment on 2026-10-12: pytest-queryguard next at b64d19c, queryspy 0.5.0 and pytest-querycount 0.4.0, with Python 3.13, SQLAlchemy 2.1.4 and pytest 9.1.1. The first 41 scenarios are the ones from an earlier comparison; the four scenarios 09d, 09e, 11d and 11e were added later for pytest-queryguard's own tests.

How each tool was run: pytest-queryguard with its defaults; queryspy with --queryspy-strict (without it, only the budgets in the scenarios fail: 2 of 45 tests); pytest-querycount with @pytest.mark.no_n_plus_one on every test that has no budget (without markers, all 45 pass). Budgets use the tool's own marker. The "queryguard, small-repeat and write-loop on" column adds queryguard_small_repeat_threshold = 2 and queryguard_write_loop_threshold = 2.

"Right verdict" is my judgement from the scenario's name (_bad should fail, _ok and _legit should pass); scenarios where I could not say are marked -. The scenarios were written for pytest-queryguard, and some of them test decisions it made on purpose (for example, three session.get() calls are below its default threshold), so the table is biased towards the tool that wrote it.

Score, on the 38 scenarios with a right verdict: pytest-queryguard 34, with the two extra rules on 35, queryspy 31, pytest-querycount 33. On the 34 of those that belong to the original 41: 30, 31, 28 and 30. These numbers measure agreement with my labels, not how useful a tool is. What the table shows:

• All three agree on most scenarios: lazy-load loops, selectinload, joinedload and subqueryload, async loops, budgets, raiseload.
• By default pytest-queryguard does not report a few runs of one statement (03b, 05a to 05c): a deliberate choice. It is also why it passes the pagination scenario 14a that the other two fail: three pages are below its repeat threshold of 5. (This table predates the rule that recognises pagination and chunked IN loads from their parameters, added on 2026-10-13; 14a passes with or without it, and 14e, whose IN lists overlap, is still reported.) With the small-repeat rule on it reports 03b and 05a to 05c too, and 03b becomes correct.
• queryspy missed the Core select() loop (13a) and the loop with literal values (14f); the other two reported them.
• 11d (a few objects refreshed after a commit()) is reported by queryspy and pytest-querycount and not by pytest-queryguard, whose column-load threshold is 5.
• Two parents that each lazy-load a relationship once (14b) are reported by all three. I labelled it "legit"; it is the smallest case of a loop, so you could label it the other way. It is the default threshold of pytest-queryguard (see the FAQ).
• Nobody reports 09, a self-referential walk up a parent chain where every node loads the next one.
• On a budget failure, pytest-queryguard and pytest-querycount list the statements; queryspy's marker prints only the counts.

Missing indexes on PostgreSQL#

14 scenarios on PostgreSQL 17.11 (docker, the official image), with pytest-queryguard --queryguard-index-check through two drivers and pytest-querycount --querycount-no-seq-scan. queryspy has no such check, so it is not in the table. The tables have 20 to 40 rows. Python 3.13, SQLAlchemy 2.1.4. The advisor ran without hypopg.

i07 is a judgement call: the two-column index can serve the filter with a full index scan, and PostgreSQL 18 may skip-scan it. pytest-queryguard reports it on PostgreSQL 16 and 17 and pytest-querycount does not. On the 13 scenarios with a right verdict, pytest-queryguard agreed with my labels on 13 with both drivers, pytest-querycount on 12. Both report the 2-row lookup table (i12), which is by design; both give you a way to exclude such tables. pytest-queryguard's finding also includes an Alembic call for simple cases and says "an expression index may be needed" for i06; pytest-querycount's suggests CREATE INDEX for plain columns and gives no suggestion for the expression.

What I did not measure#

SQLite for the index check (the page for it has its own tests), MySQL, PostgreSQL versions other than 17, async drivers in this comparison, memory and speed, other SQLAlchemy versions, and any real application. Overhead numbers are in scripts/bench_overhead.py and are for pytest-queryguard only.

Choosing#

• You want a zero-config gate in pytest with Core and text() coverage, per-statement failure messages and an index check: pytest-queryguard is built for that, and it has a baseline and SARIF for adoption.
• You also want N+1 findings in a running FastAPI, Starlette, Flask or WSGI app: look at queryspy. I did not test running it together with pytest-queryguard.
• You use queryspy in tests and want to move: see Migrating from queryspy.
• You want budgets written for you or one global ratchet: pytest-querycount (it and pytest-queryguard both register a max_queries marker; I did not test installing both).
• You are on Django: django-zeal.
• You want to assert exact SQL: pytest-capquery, after checking its license.
• You have nplusone on an old SQLAlchemy: see Migrating from nplusone.

Edit this page on GitHub