# pytest-queryguard > N+1 query detection and query budgets in pytest, for SQLAlchemy 2 and Django The documentation at https://maciejziel.github.io/pytest-queryguard/ as one Markdown file, page by page in the order of its navigation. Left out: the changelog, the design notes, the release checklist and the accuracy tables, which are on the site. A short summary is https://maciejziel.github.io/pytest-queryguard/llms.txt. --- Source: https://maciejziel.github.io/pytest-queryguard/ # pytest-queryguard A pytest plugin that fails tests with N+1 queries and enforces query budgets for SQLAlchemy 2, in sync, async and FastAPI code. On PostgreSQL 16 and newer, SQLite, MySQL and MariaDB it can also fail tests whose queries have no index to use. ORM code that looks correct can send one query per row instead of one query per page. The tests pass, because a test database holds a handful of rows. In production the same endpoint sends hundreds of queries. pytest-queryguard watches the SQL each test sends, and when it sees the pattern it fails the test and points to the line that caused it. ``` queryguard: N+1 detected Order.customer was lazy-loaded 50 times first at app/orders.py:10 in list_orders parents loaded at app/orders.py:9 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` ```bash pip install pytest-queryguard ``` It is on by default: there is nothing to import or configure. These pages describe 1.1.0rc1, a release candidate: `pip install --pre pytest-queryguard` installs it, a plain `pip install` gives 1.0.0, without the parts marked "since 1.1.0". See [Getting started](https://maciejziel.github.io/pytest-queryguard/getting-started.html#install). If pytest does not know an option, check the [changelog](https://maciejziel.github.io/pytest-queryguard/changelog.html) for the release that added it. ## What is different - **Zero configuration.** Every test is checked once it is installed; the other SQLAlchemy test plugins in the [comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html) need a marker, an option or a fixture before a test fails, and some never fail one. - **Few false alarms.** In the [head-to-head run](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions) of 2026-11-10 it flagged 2 of 143 scenarios without a problem; the other working plugins flagged 30 to 35. The corpus is the author's, so read it with that bias. - **More than lazy loads.** Repeated statements from `session.get()` loops, Core and `text()`, deferred and expired column loads, and query budgets that list every statement with the line that sent it. - **Missing indexes** on PostgreSQL, SQLite, MySQL and MariaDB, with a `CREATE INDEX` to add. - **Adoption on a large suite:** a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) so only new findings fail, and [SARIF](https://maciejziel.github.io/pytest-queryguard/sarif.html) for GitHub code scanning. What it does not do (ORMs other than SQLAlchemy and [Django](https://maciejziel.github.io/pytest-queryguard/django.html)) and where other tools are ahead: [Comparison with other tools](https://maciejziel.github.io/pytest-queryguard/comparison.html) and [Limitations](https://maciejziel.github.io/pytest-queryguard/limitations.html). How often it is right, on a corpus of 283 scenarios: [Accuracy](https://maciejziel.github.io/pytest-queryguard/accuracy.html). Coming from another tool: [nplusone](https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html), [queryspy](https://maciejziel.github.io/pytest-queryguard/migrating-from-queryspy.html). ## Where to go The path most projects take, one page each: 1. [Getting started](https://maciejziel.github.io/pytest-queryguard/getting-started.html): install, a first failing test and its fix, async code and FastAPI. 2. [A test failed: now what](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html): read the report, check the finding, fix it or leave it out on purpose. 3. [CI and GitHub Action](https://maciejziel.github.io/pytest-queryguard/ci.html): findings as pull request annotations. 4. [Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html): adopt it on an existing project; only new findings fail. 5. [Index check](https://maciejziel.github.io/pytest-queryguard/index-check.html) and [index advisor](https://maciejziel.github.io/pytest-queryguard/index-advisor.html): queries no index can serve, on [PostgreSQL](https://maciejziel.github.io/pytest-queryguard/index-check.html), [SQLite](https://maciejziel.github.io/pytest-queryguard/index-check-sqlite.html) and [MySQL and MariaDB](https://maciejziel.github.io/pytest-queryguard/index-check-mysql.html). Reference: [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html), [Configuration](https://maciejziel.github.io/pytest-queryguard/configuration.html), [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html), [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html). Before you adopt it: [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html) and [Stability and versioning](https://maciejziel.github.io/pytest-queryguard/stability.html). The source and the issue tracker are on [GitHub](https://github.com/MaciejZiel/pytest-queryguard). Further reading: [My N+1 test plugin failed 551 tests on someone else's project](https://dev.to/maciejziel/my-n1-test-plugin-failed-551-tests-on-someone-elses-project-nearly-all-of-them-were-noise-2pip), the launch article on dev.to: what a run on another project's suite found and why nearly all of it was noise. --- Source: https://maciejziel.github.io/pytest-queryguard/getting-started.html # Getting started ## Install ```bash pip install pytest-queryguard ``` It needs Python 3.10 or newer, pytest 8 or newer and SQLAlchemy 2.0.13 or newer; pip installs pytest and SQLAlchemy with it. The plugin registers itself with pytest: there is nothing to import or configure. `pytest -VV` lists it (`pytest-queryguard-1.0.0`). `pip install "pytest-queryguard[sqlalchemy]"` installs the same thing today. Use it if you want SQLAlchemy to keep coming with the plugin should a later minor release make it optional (see [stability](https://maciejziel.github.io/pytest-queryguard/stability.html#what-is-public)); if your project already lists SQLAlchemy in its own dependencies, the plain install is enough. The free-threaded builds of CPython (3.13t, 3.14t) are not a supported configuration; see the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html#does-it-work-on-free-threaded-python). ## A first test Every test is checked automatically; you do not write anything to get N+1 detection. The project below is [examples/sync-n-plus-one](https://github.com/MaciejZiel/pytest-queryguard/tree/main/examples/sync-n-plus-one), where a test runs it and checks that its README shows the output you see here. To follow along, make an empty directory and create the files of this page in it; every file is shown. `pytest.ini` puts the project directory on `sys.path`, so that the tests can `import app` (in `pyproject.toml` the same is `[tool.pytest.ini_options]` with `pythonpath = ["."]`): ```ini [pytest] pythonpath = . ``` `app/__init__.py` and `tests/__init__.py` are empty files. The models are an order that belongs to a customer. `app/models.py`: ```python from sqlalchemy import ForeignKey from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship class Base(DeclarativeBase): pass class Customer(Base): __tablename__ = "customer" id: Mapped[int] = mapped_column(primary_key=True) name: Mapped[str] class Order(Base): __tablename__ = "orders" id: Mapped[int] = mapped_column(primary_key=True) customer_id: Mapped[int] = mapped_column(ForeignKey("customer.id")) customer: Mapped[Customer] = relationship() ``` The `session` fixture creates 50 customers with one order each, in an in-memory SQLite database. It runs before the test body, so its own statements are not counted. `tests/conftest.py`: ```python from collections.abc import Iterator import pytest from app.models import Base, Customer, Order from sqlalchemy import create_engine from sqlalchemy.orm import Session @pytest.fixture def session() -> Iterator[Session]: engine = create_engine("sqlite://") Base.metadata.create_all(engine) with Session(engine) as session: session.add_all(Customer(id=i, name=f"customer {i}") for i in range(1, 51)) session.add_all(Order(id=i, customer_id=i) for i in range(1, 51)) session.commit() yield session ``` The code under test lists the orders with their customer's name. `app/orders.py`: ```python from sqlalchemy import select from sqlalchemy.orm import Session from app.models import Order def list_orders(session: Session) -> list[dict[str, object]]: rows = [] for order in session.scalars(select(Order)).all(): rows.append({"id": order.id, "customer": order.customer.name}) return rows ``` `app/customers.py`: ```python from sqlalchemy.orm import Session from app.models import Customer def fetch_customers(session: Session, ids: list[int]) -> list[Customer]: customers = [] for customer_id in ids: customers.append(session.get(Customer, customer_id)) return customers def rename_customers(session: Session, names: dict[int, str]) -> None: for customer_id, name in names.items(): session.get(Customer, customer_id).name = name session.flush() ``` `tests/test_orders.py` (the `session` fixture in `tests/conftest.py` creates 50 customers with one order each): ```python import pytest from app.customers import fetch_customers, rename_customers from app.orders import list_orders def test_list_orders(session): assert len(list_orders(session)) == 50 def test_fetch_customers(session): assert len(fetch_customers(session, list(range(1, 51)))) == 50 @pytest.mark.max_queries(2) def test_rename_customers(session): rename_customers(session, {1: "Ada", 2: "Grace"}) ``` All three tests pass without the plugin. With it installed, `pytest tests/test_orders.py --queryguard-report` gives the output below (Python 3.13, SQLAlchemy 2.1; a plain `pytest` also runs the fixed tests of the next section, if you have created them). Older versions print slightly different SQL, for example column aliases (`customer.id AS customer_id`) on SQLAlchemy 2.0, and the timing numbers differ from run to run. ``` FFF [100%] =================================== FAILURES =================================== _______________________________ test_list_orders _______________________________ queryguard: N+1 detected Order.customer was lazy-loaded 50 times first at app/orders.py:10 in list_orders called from tests/test_orders.py:7 in test_list_orders parents loaded at app/orders.py:9 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) _____________________________ test_fetch_customers _____________________________ queryguard: N+1 detected the same statement ran 50 times first at app/customers.py:9 in fetch_customers called from tests/test_orders.py:11 in test_fetch_customers kind: repeated-statement label: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#repeated-statement fix: fetch all rows in one query (WHERE id IN (...)) instead of in a loop ____________________________ test_rename_customers _____________________________ queryguard: expected at most 2 queries, got 4 1. SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/customers.py:15 in rename_customers) 2. UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) 3. SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/customers.py:15 in rename_customers) 4. UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) database time: 154 us slowest: 71 us UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) 37 us UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) 27 us SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/customers.py:15 in rename_customers) ============================== queryguard report =============================== 51 tests/test_orders.py::test_list_orders 50 tests/test_orders.py::test_fetch_customers 4 tests/test_orders.py::test_rename_customers =========================== short test summary info ============================ FAILED tests/test_orders.py::test_list_orders - Failed: queryguard: N+1 detected FAILED tests/test_orders.py::test_fetch_customers - Failed: queryguard: N+1 d... FAILED tests/test_orders.py::test_rename_customers - Failed: queryguard: expe... 3 failed in 0.08s ``` The loops are in `app/`, the code you ship, and the tests call it. A loop written in the test function itself (or in `conftest.py`, a factory or a helper under `tests/`) is test code: it never runs in production, so by default it fails no test. The run then ends with a `queryguard: test code` section that counts those findings, names the tests and says how to see them (`pytest -o queryguard_test_code=warn`). See [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code). The fixed code loads the related rows with the parent query and fetches many rows with one `IN` query. `app/orders_fixed.py`: ```python from sqlalchemy import select from sqlalchemy.orm import Session, joinedload from app.models import Order def list_orders(session: Session) -> list[dict[str, object]]: rows = [] for order in session.scalars(select(Order).options(joinedload(Order.customer))): rows.append({"id": order.id, "customer": order.customer.name}) return rows ``` `app/customers_fixed.py`: ```python from collections.abc import Sequence from sqlalchemy import select from sqlalchemy.orm import Session from app.models import Customer def fetch_customers(session: Session, ids: list[int]) -> Sequence[Customer]: return session.scalars(select(Customer).where(Customer.id.in_(ids))).all() def rename_customers(session: Session, names: dict[int, str]) -> None: customers = session.scalars(select(Customer).where(Customer.id.in_(names))) for customer in customers: customer.name = names[customer.id] session.flush() ``` `tests/test_orders_fixed.py` is the same three tests, importing the fixed modules: ```python import pytest from app.customers_fixed import fetch_customers, rename_customers from app.orders_fixed import list_orders def test_list_orders(session): assert len(list_orders(session)) == 50 def test_fetch_customers(session): assert len(fetch_customers(session, list(range(1, 51)))) == 50 @pytest.mark.max_queries(2) def test_rename_customers(session): rename_customers(session, {1: "Ada", 2: "Grace"}) ``` They pass: ``` tests/test_orders_fixed.py ... [100%] 3 passed ``` ## Async and FastAPI Nothing changes for async code. `AsyncSession` and `create_async_engine` run on a sync engine underneath, which the plugin already watches. On SQLAlchemy 2.1 and newer, async support needs `pip install "sqlalchemy[asyncio]"`, which provides greenlet. The failure points to the `await` in your code, not to SQLAlchemy internals. This endpoint (from [examples/async-fastapi](https://github.com/MaciejZiel/pytest-queryguard/tree/main/examples/async-fastapi); the models use SQLAlchemy's `AsyncAttrs` mixin) reads a relationship for each order: ```python @app.get("/orders") async def list_orders() -> list[str]: async with sessions() as session: orders = (await session.scalars(select(Order))).all() names = [] for order in orders: customer = await order.awaitable_attrs.customer names.append(customer.name) return names ``` FastAPI's `TestClient` runs the application in another thread. Queries from any thread are counted, so an N+1 inside an endpoint fails the test that called it: ```python def test_orders_endpoint(): with TestClient(app) as client: response = client.get("/orders") assert response.status_code == 200 ``` ``` queryguard: N+1 detected Order.customer was lazy-loaded 5 times first at app/main.py:37 in list_orders parents loaded at app/main.py:34 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` pytest cannot run `async def` tests by itself. With pytest-asyncio or anyio you can write a test as `async def` and use an `AsyncSession` directly. An application that gets its session from a dependency (`Depends(get_session)`) is tested by overriding the dependency with a session on the test database; the [FastAPI recipe](https://maciejziel.github.io/pytest-queryguard/recipes-fastapi.html) shows it for `TestClient` and `httpx.AsyncClient`. ## What next The path from here, in the order most projects need it: 1. [A test failed: now what](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html): read the report, check that the finding is real, fix it, or silence it on purpose. 2. [CI and GitHub Action](https://maciejziel.github.io/pytest-queryguard/ci.html): nothing to add for a plain pytest job; the action also shows the findings in pull requests. 3. [Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html): on an existing project, record today's findings so that only new ones fail. [Adopting on a legacy codebase](https://maciejziel.github.io/pytest-queryguard/recipes-legacy.html) walks through it. 4. [Index check](https://maciejziel.github.io/pytest-queryguard/index-check.html) and [index advisor](https://maciejziel.github.io/pytest-queryguard/index-advisor.html): fail tests whose queries no index can serve, with the `CREATE INDEX` to add. [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html) explains the rules and their thresholds, and the [configuration reference](https://maciejziel.github.io/pytest-queryguard/configuration.html) lists every option. --- Source: https://maciejziel.github.io/pytest-queryguard/django.html # Django pytest-queryguard checks Django ORM code as it checks SQLAlchemy code: it fails a test that runs an N+1, enforces query budgets, and writes the same baseline, JSON and SARIF files. Since 1.1.0 the Django support is no longer experimental: its finding kinds, labels and supported versions follow the [stability policy](https://maciejziel.github.io/pytest-queryguard/stability.html#what-is-public) like the rest of the plugin (it was experimental from 0.10.0 to 1.0.x). The test runner for `manage.py test` is new in 1.1.0 and still [experimental](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental). It is not related to the `django-query-guard` and `django-queryguard-n1` packages on PyPI. ## Getting started ```bash pip install "pytest-queryguard[django]" pytest-django ``` It needs Django 5.2, 6.0 or 6.1 and works next to [pytest-django](https://pytest-django.readthedocs.io/): nothing goes into `INSTALLED_APPS`, `MIDDLEWARE` or your settings, and there is nothing to import. A project that already runs its tests with pytest-django is checked from the next run on. A model with a foreign key: ```python # library/models.py from django.db import models class Author(models.Model): name = models.CharField(max_length=100) class Book(models.Model): title = models.CharField(max_length=200) author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="books") ``` a function that reads the author of each book: ```python # library/catalog.py from library.models import Book def book_lines(): return [f"{book.title} by {book.author.name}" for book in Book.objects.all()] ``` and a test that calls it: ```python # tests/test_books.py import pytest from library.catalog import book_lines from library.models import Author, Book @pytest.fixture def books(db): for i in range(3): author = Author.objects.create(name=f"author {i}") Book.objects.create(title=f"book {i}", author=author) def test_book_lines(books): assert len(book_lines()) == 3 ``` The test fails, at the end of the test, with: ```text queryguard: N+1 detected Book.author was lazy-loaded 3 times first at library/catalog.py:6 in book_lines called from tests/test_books.py:16 in test_book_lines parents loaded at library/catalog.py:6 in book_lines kind: relationship-load label: Book.author docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT "library_author"."id", "library_author"."name" FROM "library_author" WHERE "library_author"."id" = %s LIMIT 21 fix: load it with the parent query, e.g. Book.objects.select_related("author") or, on Django 6.1+, .fetch_mode(models.FETCH_PEERS) on that query ``` With `Book.objects.select_related("author")` the test passes. The fixture's writes are not measured: only the test function's body is, as for SQLAlchemy. ## Without pytest (manage.py test) A project that runs its tests with Django's own runner (`manage.py test`, unittest `TestCase`s) gets the same detection from a test runner, with no change to the tests. Two lines in the settings: ```text TEST_RUNNER = "pytest_queryguard.django.QueryGuardRunner" QUERYGUARD = {"mode": "fail"} # optional: the default ``` ```bash pip install "pytest-queryguard[django]" python manage.py test ``` `QueryGuardRunner` is Django's `DiscoverRunner` with each test measured as the pytest plugin measures it: `setUp()`, the test method, `tearDown()` and the cleanups. `setUpClass()`, `setUpTestData()` and Django's own database set-up are not measured, as pytest fixtures are not. With the models above, a helper that reads the author of each book: ```python # library/listing.py from library.models import Book def book_lines(): return [f"{book.title} by {book.author.name}" for book in Book.objects.all()] ``` and a test case that calls it: ```python # library/tests.py from django.test import TestCase from library.listing import book_lines from library.models import Author, Book class BookTests(TestCase): @classmethod def setUpTestData(cls): for i in range(3): author = Author.objects.create(name=f"author {i}") Book.objects.create(title=f"book {i}", author=author) def test_book_lines(self): self.assertEqual(len(book_lines()), 3) ``` the test fails with the plugin's report: ```text FAIL: test_book_lines (library.tests.BookTests.test_book_lines) ---------------------------------------------------------------------- AssertionError: queryguard: N+1 detected Book.author was lazy-loaded 3 times first at library/listing.py:6 in book_lines called from library/tests.py:16 in test_book_lines parents loaded at library/listing.py:6 in book_lines kind: relationship-load label: Book.author docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT "library_author"."id", "library_author"."name" FROM "library_author" WHERE "library_author"."id" = %s LIMIT 21 fix: load it with the parent query, e.g. Book.objects.select_related("author") or, on Django 6.1+, .fetch_mode(models.FETCH_PEERS) on that query ``` A test that fails on its own, or is skipped, is reported as it is, without the analysis. A project with a runner of its own subclasses `QueryGuardRunner` instead of `DiscoverRunner`; a `test_runner` that picks its own result class (xmlrunner's `XMLTestRunner`) keeps it, and the tests are measured all the same. To check only some test cases, under any runner, mix `QueryGuardTestCase` in instead: ```python from django.test import TestCase from pytest_queryguard.django import QueryGuardTestCase class BookTests(QueryGuardTestCase, TestCase): ... ``` Under pytest the mixin does nothing: the plugin measures every test already. **Settings.** `QUERYGUARD` takes the names of the [ini options](https://maciejziel.github.io/pytest-queryguard/configuration.html) without the `queryguard_` prefix, with the same defaults and values: `mode` (`fail`, `warn`, `off`), `relationship_threshold`, `repeat_threshold`, `small_repeat_threshold`, `column_load_threshold`, `write_loop_threshold`, `scope`, `test_code`, `fail_on`, `ignore` (a list of [ignore patterns](https://maciejziel.github.io/pytest-queryguard/ignoring.html)), `max_events` and `stack_depth`. `python manage.py test --queryguard-mode=warn` overrides `mode`; the command line wins over `QUERYGUARD`, which wins over the defaults. `pytest.ini` and `pyproject.toml` are not read. An unknown name or a bad value stops the run with `ImproperlyConfigured` before the test database is created (with the mixin alone, at the first test it measures). **Warn mode** issues each report as a `QueryGuardWarning` at the test method, shown after the test (also with `--buffer`). Django sends warnings to the `py.warnings` logger: with the default `LOGGING` they reach stderr; a `LOGGING` of your own decides where they go. `python -W "error:queryguard:UserWarning" manage.py test` turns them into test errors (the message starts with `queryguard:`; `-W` cannot name `QueryGuardWarning`, which is not imported when Python starts). **Test code** is the modules of the test cases the runner loaded, the files below a `tests` or `test` folder of the current directory, and factories, as under pytest: with the default `test_code = off` a loop in the test method or `setUp()` is not reported, nor is a query that a loop of the test makes the application run once per pass ([Loops of the test](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#loops-of-the-test)); a loop in a view, serializer or model method it calls is. `ignore()` blocks work as under pytest. **`--parallel`** works, with `fork`, `spawn` and `forkserver` workers: each worker measures its tests and the failures come back as any test failure; warnings are printed by the worker. A `QueryGuardRunner` subclass with a `parallel_test_suite` of its own must subclass `QueryGuardParallelTestSuite`; otherwise the run stops with `ImproperlyConfigured`, as its workers would measure nothing. **Not available without pytest** (yet): the `max_queries` marker and the budget file (the `max_queries()` context manager works), the baseline, `--queryguard-json`, SARIF, the end-of-run summary, strict mode and the index check. They need pytest-django and the plugin. The runner (new in 1.1.0) is [experimental](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental), unlike the rest of the Django support: its settings and reports may change in a minor release. See the [design note](https://maciejziel.github.io/pytest-queryguard/design-django-runner.html). ## What is checked | Kind | Django code it reports | Fix the message names | |---|---|---| | `relationship-load` | a foreign key, a one-to-one relation (either side, multi-table inheritance included), a reverse foreign key, a many-to-many relation, a generic foreign key or a `GenericRelation` read for 2 or more objects of one query line; also `.filter()`, `.count()`, `.exists()` and `.values()` on such a relation | `select_related()` or `prefetch_related()` with the lookup, through a chain (`"author__publisher"`) | | `column-load` | a field left out by `.only()` or `.defer()` read for 5 or more objects | name it in `.only()`, or leave it out of `.defer()` | | `repeated-statement` | one SELECT shape run 5 or more times: `get()`, `filter(...).exists()`, `refresh_from_db()` or a serializer method that queries, per item; also through one object's relation (`author.books.get(pk=pk)` per item) | `in_bulk(ids)` or `filter(pk__in=ids)` | | `missing-index` (off by default) | a SELECT that no index serves, on SQLite, PostgreSQL (psycopg 2 or 3) and MySQL; see [Index check](https://maciejziel.github.io/pytest-queryguard/index-check.html) | the index to create | | `write-loop` (off by default) | one INSERT, UPDATE or DELETE per row: `save()`, `create()`, `delete()` in a loop | `bulk_create()`, `bulk_update()`, `queryset.update()`, `filter(pk__in=ids).delete()` | The rules, thresholds, options, markers and files are the ones described in [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html) and the [Configuration reference](https://maciejziel.github.io/pytest-queryguard/configuration.html); this page only lists what is particular to Django. Not reported: - Loads that `prefetch_related()`, `select_related()` or a `Prefetch` object answered; lookups of single objects at different lines (`Book.objects.get(pk=1).author` and, at another line, `Book.objects.get(pk=2).author`); a NULL foreign key. - Django 6.1 fetch modes: a query with `.fetch_mode(models.FETCH_PEERS)` loads the relation of all its objects at once, which is no N+1. - A delete with its cascade (`author.delete()` deleting the books and their reviews), and the batches of one `bulk_create()` or `bulk_update()`: each is one unit of work for the `write-loop` rule. - The `SAVEPOINT` and `RELEASE SAVEPOINT` statements of `transaction.atomic()` never repeat; budgets count them, as `assertNumQueries` does. - The statements Django runs to set up a new connection (on MySQL, the `SET` of the isolation level) are not counted, as `assertNumQueries` does not count them: a test that opens the connection, after a `TestCase` class closed it, counts the same as one that does not. Everything that works from these kinds works for Django: budgets (`max_queries`, the `queryguard` fixture, the budget file), `record_queries()`, `ignore()` blocks, the `queryguard_ignore` marker and option, `--queryguard-index-check` with the index advisor, the [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html), `--queryguard-json` with the pull-request comparison and the [GitHub Action](https://maciejziel.github.io/pytest-queryguard/ci.html), [SARIF](https://maciejziel.github.io/pytest-queryguard/sarif.html) and strict mode (`queryguard_strict`, which raises `NPlusOneDetected` at the attribute access that makes the N+1). Each request of the test client (one call of `client.get()`; a view called directly with `RequestFactory` is no request) always counts on its own, also with the default `queryguard_scope = test`: a test that calls a view once per object makes separate requests, each looking up its session and user once, and that is no loop of the application. The rest of the test counts as a whole. With `queryguard_scope = session`, statements outside a request also count per database connection, as a Session does for SQLAlchemy. Requests of the `AsyncClient` (and of an ASGI handler) count on their own too, on every supported Django version, and so do the requests of the live server (`live_server`, `LiveServerTestCase`), each in a thread of the server. A thread that runs test code (its target is a function of the test: a helper that runs a function in five threads to test a race) is a unit of its own as well, on its connection; a thread whose target is a function of the application is not, also when the test started it (`Thread(target=place_order)`). A streamed body (`StreamingHttpResponse`, `FileResponse`) counts in its request when the test reads it, also after other requests. See [Several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html). The N+1s of test code are left out by default, as for SQLAlchemy (`queryguard_test_code`, see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)): a loop in the test function, a fixture or a factory is not reported, nor is a query that a loop of the test makes the application run once per pass (objects created one by one whose `post_save` receiver reads a relation, a helper called per case; see [Loops of the test](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#loops-of-the-test)). A loop in a view, serializer or model method the test calls is. So is a loop in a view that runs no line of your project, through the test client or called directly: a generic view with a class-level `queryset`, its nested serializer or its template, the admin. A serializer or template the test uses itself (to build the expected data) is test code. A call of the async ORM, which runs in a thread of asgiref with no line of the test on its stack, always counts as the application's. ## Collecting queries without failing the test pytest-django's `django_assert_num_queries` checks the count when its block ends, so a wrong count fails the test before the test's own assertions run. [pytest-django#1034](https://github.com/pytest-dev/pytest-django/issues/1034) asks for a way to see the queries without that failure, for example while debugging why a test that also checks the logic now runs one query fewer. pytest-django's maintainer declined it as too niche and pointed to Django's `CaptureQueriesContext`. With pytest-queryguard there are several ways, none of them new API. `record_queries()` records the block and fails nothing; the test decides when to look at the count. Here the logic is checked first, then the count, and a wrong count prints the statements: ```python # library/services.py from library.models import Author, Book def add_book(title, author_name): author = Author.objects.create(name=author_name) return Book.objects.create(title=title, author=author) ``` ```python # tests/test_add_book.py from library.models import Book from library.services import add_book from pytest_queryguard import record_queries def test_add_book(db): with record_queries() as log: add_book("Dune", "Frank Herbert") book = Book.objects.get() assert book.author.name == "Frank Herbert" assert log.count == 2, [query.sql for query in log] ``` The other ways: - `@pytest.mark.max_queries(n)` is checked after the test body, and when the body fails, its failure is reported, not the budget. It fails only above `n`, not below (see [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html)). - `--queryguard-mode=warn` (or `queryguard_mode = warn`) turns N+1 findings into `QueryGuardWarning`s, and the test passes. Budgets are not findings: `max_queries`, `queryguard.num_queries()` and the budget file fail in every mode. - `--queryguard-report` prints the tests with the most queries at the end of the run, and `--queryguard-json=PATH` writes every test's count to a file (see [CI](https://maciejziel.github.io/pytest-queryguard/ci.html#query-counts-as-json)); neither fails a test. ## How it sees Django - **Statements** come from Django's documented [`connection.execute_wrapper`](https://docs.djangoproject.com/en/stable/topics/db/instrumentation/). The plugin puts its wrapper first in the list of every connection, so a wrapper of your own still runs and is still removed by its own `with connection.execute_wrapper(...)` block. Raw SQL through `connection.cursor()` is measured too. - **Lazy loads** are seen through a few class-level hooks, installed once Django's settings are configured and its apps are loaded: the descriptors of foreign keys and reverse one-to-one relations, the managers of reverse foreign keys and many-to-many relations, and the descriptor of deferred fields. Querysets and model instances still pickle and copy as before: the plugin attaches nothing to them that would not. - **Where the parents came from**: the plugin notes the query line of each instance a queryset builds, so lazy loads are grouped by that line as for SQLAlchemy (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load)). The objects `select_related()` builds with each row count as loaded there too, so a load below them names the whole lookup (`select_related("author__publisher")`). - **Call sites** skip the frames of Django, asgiref and Django REST framework, as they skip SQLAlchemy's: a finding points at your view, serializer or test. A view that runs no line of your project between Django and the query (a DRF generic view with a class-level `queryset` and a `ModelSerializer`, a `TemplateResponse` rendered after the view returned) is named by its class or function, with the test line that made the request as its caller: the fix belongs in the view's `queryset` or `get_queryset()`. A middleware of your project on the stack is passed over. A view of Django's own (a `ListView` set up in the URLconf) points at the test line. A call of the async ORM (`await Book.objects.aget(...)`, `async for`), which Django runs in a thread of asgiref, has the line that awaited it as its call site. ## Limitations - **Values Django reloads by itself**: on a database without `RETURNING` (MySQL), a field saved as an expression (`F("pages") + 1`) is reloaded on its next read; such reads in a loop are reported as a `column-load` whose fix names `.only()`. Generated fields are left out. - **Durations** include the time of other `execute_wrapper`s, since the plugin's wrapper is the outermost. - Some features are SQLAlchemy only by decision: see [Out of scope for Django](https://maciejziel.github.io/pytest-queryguard/django.html#out-of-scope-for-django). ## Out of scope for Django These features of the plugin are not offered for Django code, and are not planned. Each is a decision about scope, not a gap that the Django support leaving experimental (in 1.1.0) depended on. They find nothing in Django code; with SQLAlchemy in the same project they work for its code as usual. | Feature | Why not for Django | |---|---| | `unused-eager-load` (`queryguard_unused_eager_load`) | A `prefetch_related()` or `select_related()` whose objects the test never reads. Telling that apart needs a hook on every read of Django's prefetch caches and of each `select_related()` object, and it is wrong where a template or serializer reads them only for some rows: nplusone reports it and flags three of the CLEAN scenarios of the Django corpus. Its cost is one extra query, not one per row. | | `unused-columns` (`queryguard_unused_columns`) | Columns loaded and never read. For Django it would mean watching every field read of every instance; the gain is a narrower `SELECT`, which `.only()` gives where it matters. `column-load` covers the harmful direction: a field left out and then read per row. | | `cartesian-load` (`queryguard_cartesian_load`) | The rows multiplied by eager-loading two collections in one `JOIN`. `select_related()` follows only foreign keys and one-to-one relations, and `prefetch_related()` runs a query per relation, so the Django ORM does not build such a query from loader options. | | Fix patches (`--queryguard-write-patch`, `--queryguard-show-patch`) | A patch adds a loader option at the line of the parents' query. In Django that query is often a class attribute (`queryset = Book.objects.all()` of a generic view), a manager method or a chain built over several lines, so a patch would be wrong as often as right. Each message names the code to add (`select_related("author")`). | | The static check (`python -m pytest_queryguard.lint`) | It reads SQLAlchemy relationships from the source. For Django it would have to resolve models, managers and querysets across files, which a test run sees directly. | | The in-application mode (`pytest_queryguard.app`) | It watches a SQLAlchemy engine in a running application. Django has django-debug-toolbar and django-silk for that; the plugin checks Django code in its tests. | `QueryGuardRunner` (`manage.py test`) has no baseline, JSON, SARIF, budget files, strict mode or index check yet: that is a gap of the runner, not of the Django support, see [Without pytest](https://maciejziel.github.io/pytest-queryguard/django.html#without-pytest-managepy-test). ## Accuracy The Django corpus in `tests/django_project/corpus` has 75 scenarios, 38 with an N+1 or another finding and 37 without, run in five configurations: foreign keys, reverse relations, many-to-many relations, one-to-one relations, generic relations, multi-table inheritance, `select_related()`, `prefetch_related()` and `Prefetch` objects, `.only()` and `.defer()`, Django REST framework serializers, admin list, change and delete pages, templates, `get()` and `exists()` per item, `save()` and `delete()` in a loop against bulk writes and cascades, signals, `iterator()`, pagination, helpers called for objects the test created, lookup helpers called from two lines, and requests of the test client. On SQLite, with Django 5.2 and 6.1, in the default configuration: | Kind | Precision | Recall | |---|---|---| | `relationship-load` | 100 % (23 of 23) | 100 % | | `column-load` | 100 % (5 of 5) | 100 % | | `repeated-statement` | 100 % (8 of 8) | 100 % | | `write-loop` (threshold 2) | 100 % (7 of 7) | 100 % | The same holds in the other four configurations (small repeats, a column-load threshold of 2, write loops, strict mode) and on PostgreSQL 17 and MySQL 8.4, except for two scenarios with two findings each in strict mode: the test stops at the first, before the second is complete. `scripts/django_accuracy_report.py` prints them. **These numbers are biased.** We wrote the corpus, together with the integration: it says that the cases it names work, not how often the rules are right on other code. Seven of its scenarios (`clean_35` to `clean_37`, `bug_35` to `bug_38`) were added after the runs on real projects below found false positives, each before its fix. For an estimate on code we did not write, see [Real projects](https://maciejziel.github.io/pytest-queryguard/django.html#real-projects). ## Real projects The test suites of six open-source Django projects ran in GitHub Actions on 2026-11-07, each once without the plugin, once with it in warn mode, and once under each of [django-zeal](https://maciejziel.github.io/pytest-queryguard/django.html#comparison) and nplusone (the `django` suite of `.github/workflows/realworld.yml`; projects, tags and commands in `scripts/realworld_django_projects.json`). Final run: [42420546251](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42420546251); the first one, before the fixes below: [42416001785](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42416001785). | Project | Tests run | Passed / failed / skipped without the plugin | Change with the plugin | Internal warnings / errors | Findings | Overhead, two runs | |---|---|---|---|---|---|---| | Django REST framework 3.18.3 (Django 6.1) | all | 1655 / 0 / 9 | none | 0 / 0 | 38: 32 relationship-load, 6 repeated-statement | −5.7 %, −2.9 % (a 6 s suite) | | Read the Docs 2026.11.03 | api, projects, builds, organizations | 585 / 0 / 5 | none | 0 / 0 | 45: 15 relationship-load, 28 repeated-statement, 2 column-load | +1.7 %, −0.3 % | | django-cms 5.1.3 | all | 1781 / 1 / 70 | none | 0 / 0 | 2539: 521 relationship-load, 2017 repeated-statement, 1 column-load | +15.9 %, +8.6 % | | pretix 2026.9.0 | `tests/api` | 1654 / 1 / 0 | none | 0 / 0 | 378: 124 relationship-load, 254 repeated-statement | +2.2 %, −2.0 % | | saleor 3.23.47 (PostgreSQL) | the query-count benchmarks and product queries | 1487 / 0 / 0 | none | 0 / 0 | 258: 233 relationship-load, 25 repeated-statement | −1.4 %, −2.9 % | | django-oscar 4.2.1 (PostgreSQL) | functional and integration | 1697 / 0 / 0 | none | 0 / 0 | 641: 278 relationship-load, 363 repeated-statement | +3.7 %, +8.4 % | The plugin changed no test's outcome and reported no internal error in any of the 8,945 tests, in either run. The overheads are of single runs (the first before SQLAlchemy was imported lazily, the second in [run 42422111060](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42422111060) with the final code), and the runs without any tool vary by up to 30 % between runs of the workflow, so only django-cms stands out: it runs about 90 statements in each test body, and the cost per statement (about 15 µs on a laptop: finding the call site and recording the statement) shows there. django-zeal and nplusone added between −8 % and +3 % in the same runs. **Triage.** All 38 findings of Django REST framework and 12 distinct finding sites drawn at random from each other project (98 in all) were read in the projects' code: | Verdict | Count | What they are | |---|---|---| | true | 68 | a relation or the same query per item in a loop of the application: serializers and GraphQL resolvers reading a relation per row, signal receivers per saved row, tree walks, per-row deletes | | debatable | 28 | the same query at several lines of straight test code (fixtures made one by one, assertions), a loop of the test over cases or pages, settings looked up again and again in one request | | false | 2 | django-oscar's concurrency test: five threads, each placing one order on its own connection, counted together | The first run had 5,071 findings in the five projects that ran (django-oscar did not: it needs PostgreSQL); the same five have 3,258 now. The false positives it showed, each fixed with a scenario added first: - **A test that makes several requests** (Read the Docs, pretix, django-cms, DRF): every request looks up its session, user, token or settings once, and those lookups were counted together. Each request of the test client now counts on its own (`clean_36`, `bug_37`); pretix went from 861 to 254 `repeated-statement` findings. - **One helper, two objects the test created** (Read the Docs: `Project.save()` reads `self.versions` of a project made in `setUp` and one made in the test, 210 findings; saleor 85; django-cms about 170): loads of objects of unknown origin are now grouped by the call path of the read, not by its line alone (`clean_35`, `bug_35`, `bug_36`). - **Django's own test-case machinery** (DRF, django-cms): the flush and `post_migrate` of `TransactionTestCase` tear-downs ran content type and permission queries inside the measured call; nothing is recorded in `_pre_setup` and `_post_teardown` now (a test in `tests/django_project`; the corpus cannot hold a `TransactionTestCase`). Fixed since: work spread over threads (the two false findings above) counted together with `queryguard_scope = test`. A thread that test code starts (its target is test code, as `oscar.test.utils.run_concurrently` is) has a connection of its own, and its statements now count on their own, as a request does. A thread that the application starts, one per item, is still counted with the rest of the test. ### Five more projects (2026-11-14) A second run took five more projects, chosen for having pytest-django suites that the first run did not cover: a document manager with a DRF API (paperless-ngx), a recipe manager with a DRF API (Tandoor), an authentication library (django-allauth), a GraphQL library with sync and async test clients (strawberry-django) and a labelling tool (Label Studio). All ran on Django 5.2 and SQLite. Same workflow and settings as above. The final run, with the two fixes below: [43599524757](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43599524757). The first runs, before them: [43587676195](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43587676195) and [43588110966](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43588110966). | Project | Tests run | Passed / failed / skipped without the plugin | Change with the plugin | Internal warnings / errors | Findings (first run → final) | Overhead, two runs | |---|---|---|---|---|---|---| | paperless-ngx 3.4.2 | the API and workflow tests of `src/documents` | 713 / 0 / 0 | none | 0 / 0 | 167 → 167: 138 relationship-load, 29 repeated-statement | +0.6 %, −1.7 % | | Tandoor 2.7.2 | `cookbook/tests/api` | 677 / 7 / 0 | none in the final run (see below) | 0 / 0 | 243 → 243: 216 relationship-load, 27 repeated-statement | 0.0 %, −0.9 % | | django-allauth 65.22.1 | all | 2500 / 0 / 1 | none | 0 / 0 | 54 → 51: 2 relationship-load, 49 repeated-statement | +2.2 %, +6.9 % | | strawberry-django 0.96.3 | all | 1278 / 0 / 69 | none | 0 / 0 | 131 → 97: 96 relationship-load, 1 repeated-statement | −0.6 %, −3.3 % | | Label Studio 1.23.2 | `data_manager`, `projects`, `tasks`, `organizations`, `users` and `tests/data_manager` | 222 / 0 / 11 | none | 0 / 0 | 297 → 243: 163 relationship-load, 80 repeated-statement | −6.9 %, −6.0 % | In all 5,478 tests, in both runs, the plugin changed no test's outcome and reported no internal warning or error. The exception is one test of Tandoor in the first run: `test_inherit[...-supermarket_category-False-cat_1]` failed with the plugin only. That test makes its categories with `get_or_create` on a random `faker.word()` name, so two of them can come out as one. It passed in every later run and in the runs under django-zeal and nplusone. Tandoor's seven failures without the plugin depend on the date and on the order of the tests; they fail the same way with it. **Triage.** 51 distinct finding sites of the first runs were read in the projects' code: all 3 of django-allauth's, and 12 drawn at random from each other project. | Verdict | Count | What they are | |---|---|---| | true | 37 | DRF serializers and GraphQL resolvers reading a relation per row (most of paperless-ngx, Tandoor and strawberry-django), per-row work in signal handlers and delete actions, a migration that reads the filters of each group | | debatable | 12 | 11 where test code drives the repetition: a test that loops over cases or calls one function ten times, fixtures and factories that create objects one by one, assertions per object. And one query that runs six times in one request (django-allauth's `is_mfa_enabled`), which could be cached but is not a loop | | false | 2 | strawberry-django: `User.user_permissions` of the user of each async request, counted together; django-allauth: `UserSession.user` read once for each of the two sessions of one request | Both false positives are fixed, each reproduced first: - **Requests of the `AsyncClient` on Django 5.2 and 6.0**: before Django 6.1, `Signal.asend` runs the receivers of `request_started` in a task of their own, so the scope of each request was lost and a test's requests counted together. Async handlers now open the request scope themselves, and that includes a streamed body that the test reads after the call has returned. strawberry-django went from 131 to 97 findings: 30 of the `User.user_permissions` findings above and 4 `Project.milestones` findings of tests that query one project per request. Tests in `tests/django_project/test_statements.py`; this is not a corpus scenario, because an async view cannot share the corpus's transaction on SQLite. - **One lookup helper called from two lines** (django-allauth): parents that one query line loaded are now also grouped by the call path of the read, so a helper that gets one object and reads its relation is a loop only when it runs in one (`clean_37`, `bug_38`). Label Studio lost 54 `Task.project` findings the same way: a test that creates its annotations one by one at four lines, each save of which reads the task's project. Fixed since: a finding whose rows a DRF view reads with no line of the project in the call (a `ModelSerializer`, a generic view) pointed at the first project frame on the stack. In paperless-ngx, Tandoor and Label Studio that frame was a middleware's `get_response(request)` line. It now names the view class, with the test line as its caller (see [How it sees Django](https://maciejziel.github.io/pytest-queryguard/django.html#how-it-sees-django)). The same middleware, when it is sync and the request async, was named for the async ORM calls of the view; they now name the line that awaited them. ### MySQL, Django 6.0 and `manage.py test` (2026-11-15) Three more jobs cover what the runs above lacked: a project on MySQL, one on Django 6.0, and one whose suite runs with `manage.py test` under `QueryGuardRunner` instead of pytest. Same workflow; a project with a `test_command` runs it twice, with `--testrunner` set to Django's runner and to `QueryGuardRunner` with `--queryguard-mode warn`, through `scripts/realworld_runner.py`, which writes the same JUnit XML and JSON of findings as the pytest runs. Run [43741288589](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43741288589), plugin at `main` (1.0.0 and the Django changes merged after it, not those of the open pull requests). | Project | Tests run | Passed / failed / skipped without the plugin | Change with the plugin | Internal warnings / errors | Findings | Overhead, one run | |---|---|---|---|---|---|---| | django-oscar 4.2.1, MySQL 8.4, Django 5.2 (pytest) | functional and integration | 1415 / 281 / 1 | none | 0 / 0 | 244: 180 relationship-load, 64 repeated-statement | +7.0 % | | django-allauth 65.22.1, Django 6.0 (pytest) | all | 2500 / 0 / 1 | none | 0 / 0 | 51: 2 relationship-load, 49 repeated-statement | +11.3 % | | django-taggit 7.0.0, Django 6.0 (`manage.py test`, `QueryGuardRunner`) | all | 396 / 0 / 7 | none | 0 / 0 | 54: 3 relationship-load, 51 repeated-statement | +2.8 % | django-oscar's suite is not written for MySQL: the 281 failures are MySQL errors (241 of them "You can't specify target table ... for update in FROM clause", from the category tree), the same with and without the plugin. On the tests that pass, the plugin's findings are those of the PostgreSQL run: the 45 distinct sites start with the product list's per-product reads (`Product.stockrecords`, `Product.product_class`, `Product.categories` of the search index), all true. Labels carry MySQL's backquotes; the [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html#what-an-entry-is) writes them without. django-allauth on Django 6.0 reports the same two sites as on 5.2 (the `is_mfa_enabled` lookup repeated in one request, and `SocialAccount.user`). django-taggit, under `QueryGuardRunner`: every test passed and failed as with Django's runner, and no internal warning or error. 50 of the 54 findings are one site, `_TaggableManager.add()`, which runs `get_or_create()` per tag (`managers.py:198`), in the `setUp` of the admin and model tests that add several tags at once: a loop of the library's own, true. The others: the tag lookup per natural key, `TaggedItem.__str__` reading its object and tag, and the admin's merge view reading each item's content type. Not covered yet: a large `manage.py test` suite (Wagtail, Zulip) and Django 6.0 or MySQL on a project with a bigger ORM surface than these. ### All fourteen with the 1.1.0 changes (2026-11-15) All fourteen projects of `scripts/realworld_django_projects.json` with `main` after the 1.1.0 Django changes (the view named instead of the middleware, loops of the test as test code, threads of the test on their own, the overhead work), run [43747770042](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43747770042): | Project | Passed / failed / skipped without the plugin | Change with the plugin | Internal warnings / errors | Findings | Overhead, one run | |---|---|---|---|---|---| | Django REST framework | 1655 / 0 / 9 | none | 0 / 0 | 1 | −4.6 % | | django-oscar (PostgreSQL) | 1697 / 0 / 0 | none | 0 / 0 | 380 | +8.3 % | | saleor (PostgreSQL) | 1487 / 0 / 0 | none | 0 / 0 | 166 | −0.9 % | | pretix | 1654 / 1 / 0 | none | 0 / 0 | 303 | +2.7 % | | Read the Docs | 585 / 0 / 5 | none | 0 / 0 | 12 | −0.6 % | | django-cms | 1781 / 1 / 70 | none | 0 / 0 | 384 | +16.1 % | | paperless-ngx | 713 / 0 / 0 | none | 0 / 0 | 137 | +6.8 % | | Tandoor | 677 / 7 / 0 | none | 0 / 0 | 235 | +4.5 % | | django-allauth | 2500 / 0 / 1 | none | 0 / 0 | 51 | +8.1 % | | strawberry-django | 1278 / 0 / 69 | none | 0 / 0 | 97 | −0.9 % | | Label Studio | 222 / 0 / 11 | none | 0 / 0 | 104 | −7.4 % | | django-oscar (MySQL 8.4) | 1415 / 281 / 1 | none | 0 / 0 | 164 | +6.5 % | | django-allauth (Django 6.0) | 2500 / 0 / 1 | none | 0 / 0 | 51 | +6.5 % | | django-taggit (`manage.py test`) | 396 / 0 / 7 | none | 0 / 0 | 53 | +5.6 % | Against `main` before these changes (the same harness with `plugin-ref` set to it, run [43749719108](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43749719108) and [43749400420](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/43749400420)): django-cms 683 → 384, Label Studio 243 → 104 and paperless-ngx 167 → 137 findings, Django REST framework 1 → 1. The findings that fell away moved to the test-code section, which grew by the same number (django-cms 148 → 447, Label Studio 8 → 147, paperless-ngx 44 → 74): loops of the test that call the application once per pass, such as django-cms's `create_page_content()` per page and language in `test_get_page_choices_with_multiple_translations`, and Label Studio's annotations created one by one. paperless-ngx's `WorkflowAction` findings now name `views.py` instead of the middleware. ## Comparison The Django corpus under each tool, in GitHub Actions on 2026-11-07 ([run 42421653867](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42421653867); `scripts/head_to_head/django_corpus.py`, `head-to-head.yml` with `suite=django`). Each tool as its documentation says to make it fail a test: django-zeal 2.3.0 in `INSTALLED_APPS` with `zeal_context()` around each test call (it raises at the first N+1); nplusone 1.0.0 in `INSTALLED_APPS` with its `Profiler`. Django 5.2, SQLite: | Tool | Precision | Recall, all BUG | `relationship-load` P / R | `repeated-statement` P / R | `column-load` P / R | |---|---|---|---|---|---| | pytest-queryguard, defaults | 100 % | 89 % (`write-loop` is off by default) | 100 / 100 % | 100 / 100 % | 100 / 100 % | | pytest-queryguard, write loops on | 100 % | 100 % | 100 / 100 % | 100 / 100 % | 100 / 100 % | | django-zeal 2.3.0 | 93 % | 70 % | 90 / 86 % | 67 / 29 % | 100 / 80 % | | nplusone 1.0.0 | 84 % | 43 % | 100 / 68 % | n/a | n/a | - django-zeal misses reverse many-to-many reads, `count()`, `filter()` and `exists()` per row, `refresh_from_db()`, a serializer method that queries and generic relations; it flags `clean_35` and `clean_36`, the two cases our own first real-project runs got wrong. Its `get()` check is our `repeated-statement` for `get()` only. - nplusone reports an unused eager load in three CLEAN scenarios (a kind the corpus does not score for Django, so each counts against it) and does not report `.count()`, generic relations or the deferred-field loads. On Django 6.1 it crashes (`ValueError: too many values to unpack`) in every query with `select_related()`: 8 scenarios there, and 15 tests of Django REST framework. - The bias above holds here too, and more: the corpus was written by us, for this plugin's rules. The kinds a tool does not claim are left out of its per-kind columns, but its overall recall counts every BUG scenario. What each tool reports on the real projects (the final run of each set above; reports counted once per test and message): | Project | pytest-queryguard findings | django-zeal reports (tests) | nplusone reports (tests) | |---|---|---|---| | Django REST framework | 38 | 112 (97) | 36 (36), and 15 tests it broke | | Read the Docs | 45 | 1445 (430) | 225 (138) | | django-cms | 2539 | 2704 (980) | 768 (512) | | pretix | 378 | 1479 (515) | 2756 (771) | | saleor | 258 | 461 (292) | 1615 (1195) | | django-oscar | 641 | 2875 (863) | 986 (495) | | paperless-ngx | 167 | 509 (179) | 4876 (443) | | Tandoor | 243 | 1013 (536) | 59 (31), and 403 tests it broke | | django-allauth | 51 | 1168 (639) | 16 (16) | | strawberry-django | 97 | 515 (307), and 1 test it broke | 257 (189), and 1 test it broke | | Label Studio | 243 | 459 (101) | 482 (63) | In Tandoor, nplusone broke 403 tests: Django's local-memory cache cannot pickle a queryset once nplusone has patched `QuerySet._clone`. django-zeal's largest groups are the patterns fixed above: `sessions.Session.get()` once per request (DRF, Read the Docs) and `Project.versions` read by `Project.save()` (Read the Docs, 225 times). nplusone's are mostly unused eager loads (`OrderPosition.checkins`, 294 times in pretix). ### Overhead against the other tools A 300-test pytest-django suite of the test project (each test reads 18 books with `select_related()`, gets three books and counts them; no N+1), Django 5.2, 9 interleaved rounds on one runner (`scripts/head_to_head/django_overhead.py`, same run), against the same suite with no tool: | | pytest-queryguard | django-zeal | nplusone | |---|---|---|---| | added wall time, best / median round | +1.3 % / +3.0 % | +2.0 % / −0.5 % | +6.0 % / +2.4 % | | fixed cost per pytest run (median) | +28 ms | −12 ms (noise) | −9 ms (noise) | | added per test (median) | +181 µs (+2.5 %) | −7 µs (noise) | +247 µs (+3.5 %) | Before the work on this ([run 42418336858](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42418336858)) the plugin added 10 % to that suite: 278 ms per run, nearly all of it importing SQLAlchemy in a project that does not use it, and 722 µs per test. SQLAlchemy is now imported only once the project imports it; between tests the plugin's execute wrapper is off; and the hooks return at once while nothing is measured. django-zeal records no statements, only relation reads, so it has less to do per statement; pytest-queryguard records every statement for the budgets and the `repeated-statement` rule. ## Overhead `scripts/bench_django_overhead.py` times three workloads in-memory on SQLite with Django 6.1 and Python 3.15, each in a fresh process: one `get()` per statement, iterating books with `select_related()` (the cost per instance) and reading `book.author` of each book (a lazy load each). Median of 7 runs on a laptop, in microseconds per operation: | Workload | Not installed | Installed, not measuring | Measuring | |---|---|---|---| | `get()` | 129 | 134 (+4 %) | 157 (+21 %) | | a row with `select_related()` | 6.8 | 6.8 | 7.4 (+9 %) | | a lazy load | 155 | 156 (+1 %) | 197 (+28 %) | The cost is per statement and per lazy load (finding the call site, recording the event). On a test suite, where statements are a part of each test's time, the share is lower: see the suite above and the real projects. --- Source: https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html # A test failed: now what A test that passed yesterday now fails with `queryguard: N+1 detected`. This page is the checklist: read the report, decide whether the finding is real, then fix it or leave it out on purpose. Nothing here needs a change to the plugin's configuration unless you decide to silence something. ## 1. Read the report ``` queryguard: N+1 detected Order.customer was lazy-loaded 50 times first at app/orders.py:10 in list_orders called from tests/test_orders.py:7 in test_list_orders parents loaded at app/orders.py:9 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` - The second line says **what repeated** and how often: here one relationship of 50 different orders. - `first at` is the **line of your code** that sent the first of those statements: the first stack frame outside SQLAlchemy, pytest, the standard library and `site-packages`. If it points to your test file instead of the application, the application is probably installed non-editable into `site-packages` (see [Limitations](https://maciejziel.github.io/pytest-queryguard/limitations.html)). - `called from` lines are the lines of your code that called it, innermost first, up to the test: the path through your helpers, with the frames of SQLAlchemy, pytest and the plugin left out. They are recorded the first time that line runs in the test. `queryguard_stack_depth` sets how many are shown (3 by default, `0` for none). - `parents loaded at` (relationship loads only) is the line that ran the query whose rows became the parent objects: the place for the loader option, even when the query is built in a helper and the loop is somewhere else. Parents reached through other relationships (`order.customer.country`) name the query at the start of that chain, and the `fix` line chains the loaders: `select(Order).options(joinedload(Order.customer).joinedload(Customer.country))`. The line is left out when the plugin cannot tell, for example for objects the test created and the query handed back without reading them, or objects loaded before the test body started; the hint then names the relationship's own class. It is also left out when two queries from different places read the same objects, since the plugin cannot tell which result the loop uses. An object that a later query returns from the Session without reading its row again keeps the query that loaded it. - `kind` and `label` name the finding the way ignore patterns, the `queryguard_ignore` marker and the baseline do: `relationship-load Order.customer` is the pattern for this one. For a repeated statement the label is the normalized statement, which takes the place of a separate line; a statement longer than 200 characters is cut and ends with `*`, so the label as printed still matches. - `docs` links to the section of [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html) that explains this kind of finding: what the rule counts, what it leaves out and why. - `sql` is one of the statements, as SQLAlchemy rendered it. - `fix` is the usual remedy for this kind of finding. It is a hint, not a patch: check it against what the code needs. The `kind:` line is what you need to silence a finding; the table below shows how each headline maps to the kind and label, for the cases where you want to write a pattern with a wildcard. | The report says | Kind | Label (for ignore patterns and the baseline) | Usual fix | |---|---|---|---| | `Order.customer was lazy-loaded 50 times` | `relationship-load` | `Order.customer` | `joinedload` (many-to-one) or `selectinload` (collection) on the query that loaded the parents | | `the same statement ran 7 times` | `repeated-statement` | the normalized SQL, on the `kind:` line | one query with `WHERE id IN (...)`, or a join, instead of a loop | | `Customer had its columns reloaded 50 times for 50 instances, after commit(), ...` | `column-load` | `Customer (expired)` | `expire_on_commit=False`, or load the objects again with one query | | `Engineer loaded its subclass columns on its own 50 times ...` | `column-load` | `Engineer (polymorphic)` | `selectin_polymorphic(Employee, [Engineer])` or `with_polymorphic` on the query, or `polymorphic_load` on the mapping | | `Customer.name was loaded on its own 50 times for 50 instances (deferred column)` | `column-load` | `Customer.name` | `undefer(Customer.name)`, or drop `defer()` / `load_only()` | | `the same INSERT ran 6 times, one row at a time` (opt-in) | `write-loop` | the normalized `INSERT`, `UPDATE` or `DELETE` | `session.add_all()` and one flush, or `session.execute(insert(Model), rows)` | | `Customer.notes and Customer.orders were joined into one query side by side, once` (warns by default) | `cartesian-load` | `Customer.notes + Customer.orders` | `selectinload` for all collections but one, see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#cartesian-load) | | `Customer.orders was loaded with selectinload and never read` (experimental, off by default) | `unused-eager-load` | `Customer.orders` | drop the loader option, see [Unused eager loads](https://maciejziel.github.io/pytest-queryguard/unused-eager-load.html) | | `Account: 12 columns loaded, 9 never read` (experimental, off by default) | `unused-columns` | `Account` | `load_only()` the columns the code reads, or `defer()` the large ones; see [Unused columns](https://maciejziel.github.io/pytest-queryguard/unused-columns.html) | | `queryguard: missing index` (opt-in) | `missing-index` | the table | the `CREATE INDEX` on the `fix:` line; see the [index advisor](https://maciejziel.github.io/pytest-queryguard/index-advisor.html) | | `queryguard: expected at most 2 queries, got 4` | a budget, not a finding | none | fix the code, or raise the budget; ignore patterns and the baseline do not apply | To list the kind and label of every finding of a run in one file, write a scratch baseline: ```console pytest --queryguard-baseline=findings.json --queryguard-update-baseline ``` Then read `findings.json` and delete it. A budget test still fails this run, since the baseline does not apply to budgets. The SARIF file (`--queryguard-sarif=PATH`) carries the `kind:` line in each message and the kind as the `queryguard/` rule id. ### The same finding in many tests A loop in a shared helper or fixture is reported by every test that runs it, and each of them prints the same block. After the run, the summary names such a finding once: ``` ========== queryguard: the same finding in several tests ========== 30 tests relationship-load Order.customer (900 times in total, from one place in the code; e.g. tests/test_orders.py::test_list[0]) a finding from one place in the code is fixed once for all its tests ``` A finding is listed when two tests or more reported it, failing or as a warning, grouped by kind and label. "From one place in the code" means every test reached it through the same function; with several places, the same relationship or statement is loaded in a loop in more than one function. The example is the first of the tests by name. Ignored and baselined findings are not counted, a test that runs again (a rerun plugin) counts once, and it works the same with pytest-xdist. ### Strict mode: fail at the access The report comes when the test ends. With `queryguard_strict = true` (or `--queryguard-strict`) the N+1 fails the test where it happens instead: the lazy load of a relationship for the second parent loaded at the same line (`queryguard_relationship_threshold`, 2 by default) raises `NPlusOneDetected`, and the traceback ends at the line that read the attribute, the frames of SQLAlchemy and the plugin left out: ``` def list_orders(session): names = [] for order in _helper_query(session): > name = order.customer.name ^^^^^^^^^^^^^^ E pytest_queryguard.NPlusOneDetected: queryguard strict: Order.customer was lazy-loaded for 2 parents loaded at the same line; this access is the N+1 E E Order.customer was lazy-loaded 2 times E first at app/orders.py:13 in list_orders E called from tests/test_orders.py:5 in test_list_orders E parents loaded at app/orders.py:7 in _helper_query E kind: relationship-load label: Order.customer E docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load E fix: load it with the parent query, e.g. E select(Order).options(joinedload(Order.customer)) E E (queryguard_strict raises at the lazy load instead of at the end of the E test; a queryguard_ignore marker or pattern, an ignore() block or a E baseline entry lets it pass, as for the report) ``` It is Rails' `strict_loading!(mode: :n_plus_one_only)` and Laravel's `preventLazyLoading()` for SQLAlchemy: - Reading the relationship of one object never raises, and neither do objects whose query is unknown (made by the test, loaded before it). Objects loaded one by one at the same line (`for id in ids: get_order(id).customer`) count together, as in the report. The report at the end still covers the rest (there an object whose query is unknown counts with every query line), and with `queryguard_scope = session` each Session counts on its own here too. - The finding is the one the report makes, at the first lazy load, so ignore patterns with `file=`/`function=` and baseline entries match it. The analysis at the end still runs: SARIF, `--queryguard-json` and the summary include the N+1, and the exception replaces the report's text. - A query or database-time budget the test went over before the access (`max_queries` or `max_db_time` marker, `queryguard_max_queries`, the budget file, a `max_queries()` block) is shown under the N+1 in the exception, with the statements counted until the test stopped. A budget the rest of the test would have gone over is not known. - What the test would have run after the access is unknown, as for a test that fails on its own: a `queryguard_ignore` pattern of the test or an `ignore()` block it entered is not listed under "stale ignores" for it. - It raises only what would fail the test anyway: in `fail` mode, for an N+1 that no `queryguard_ignore` marker or pattern or baseline entry covers. It does not raise while `--queryguard-update-baseline` records the findings. - Code that catches `AssertionError` around the loop does not hide the N+1: the report at the end still fails the test. - A library that catches the exception and raises its own (Pydantic's `from_attributes` validation, FastAPI's `response_model`) fails the test with that error, the strict message usually inside it. The same goes for code that swallows the exception when the test then fails on its own. The analysis at the end still runs for such a test: SARIF, `--queryguard-json` and the summary include the N+1. When the error does not already carry the strict message, the report is shown in a "Captured queryguard call" section under the failure. The test's outcome stays that of its own error. - `--no-queryguard-strict` turns strict mode off for one run, for example to see every N+1 of a test in the report instead of the first one. - It raises before the lazy load's `SELECT` is prepared: nothing is flushed, no connection is used, and engine listeners such as `handle_error` never see the exception. For that, strict mode adds a `do_orm_execute` listener, which makes SQLAlchemy prepare each ORM statement twice: a strict run costs more per ORM statement than a default one. - Only lazy loads that ran their `SELECT` count towards the threshold, as in the report: a load that a `do_orm_execute` listener answers without one (a result cache), or that SQLAlchemy rejects before sending it, never counts and never raises. Lazy loads that several threads or asyncio tasks start at the same time count once their `SELECT`s run, so the one that makes the N+1 may not raise; the report at the end still fails the test. ## 2. Is it real? Most findings are real: the code ran one statement per row, and the test database only hides the cost because it holds few rows. Look closer when: - **The test makes several requests**, for example five calls through a test client, and the repeated statement is an authentication or settings lookup. The report says `across N different Sessions or connection checkouts` in that case. Nothing loops; set `queryguard_scope = session`, see [Several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html). - **The loop is pagination or a batched `IN (...)` load** that runs five or more pages or chunks. The repeat rule counts each page; see [Limitations](https://maciejziel.github.io/pytest-queryguard/limitations.html). - **Two parents each load a relationship once.** That is reported by default, as the smallest N+1; the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html) explains the threshold and how to raise it. `--queryguard-report` prints how many statements each test ran, and [`record_queries()`](https://maciejziel.github.io/pytest-queryguard/python-api.html) lists every statement of a block with its call site, if you want to look at them in the test itself. ## 3. Fix it Apply the hint at the line the report names and run the test again. The `fix:` line shows the loader option, not its import: add `joinedload` or `selectinload` to the file's `from sqlalchemy.orm import` line, or the hint raises `NameError`. Two patterns cover most cases: ```python from sqlalchemy import select from sqlalchemy.orm import joinedload, selectinload # a many-to-one read for every row: join it into the parent query orders = select(Order).options(joinedload(Order.customer)) # a collection read for every row: one extra query for all of them customers = select(Customer).options(selectinload(Customer.orders)) # a session.get() or a SELECT in a loop: one query with IN rows = session.scalars(select(Customer).where(Customer.id.in_(ids))).all() ``` ### A patch for the parent query Since 0.8.0; experimental (see [Stability](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). For a `relationship-load` finding, pytest-queryguard can write that change for you. `--queryguard-show-patch` (or `queryguard_show_patch = true`) prints a unified diff under the finding, and `--queryguard-write-patch=PATH` writes the diffs of the whole run to one file: ``` pytest --queryguard-write-patch=queryguard.patch git apply queryguard.patch # from the rootdir ``` ```diff --- a/app/orders.py +++ b/app/orders.py @@ -1,9 +1,9 @@ from sqlalchemy import select -from sqlalchemy.orm import Session +from sqlalchemy.orm import Session, joinedload from app.models import Order def list_orders(session: Session) -> list[Order]: - orders = session.scalars(select(Order)).all() + orders = session.scalars(select(Order).options(joinedload(Order.customer))).all() return [order.customer.name for order in orders] ``` The option goes on the `select(Order)` or `session.query(Order)` call of the line in `parents loaded at`: as `.options(...)` right after the call, or as one more argument of the `.options(...)` already in its chain. When that line runs a statement built earlier in the function (`statement = select(Order)` and then `session.scalars(statement)`), the option goes on the line that builds it. A class named through its module (`select(models.Order)`) is named the same way in the option: `joinedload(models.Order.customer)`. The loader is `joinedload` or `selectinload`, the same as in the `fix:` hint, chained through the relationships that reached the parents. A loader the module does not import yet is added to its `from sqlalchemy.orm import` line, or on a new line after the imports at the top of the file. A wrong patch is worse than none, so a finding gets one only when the line is certain, and otherwise only the `fix:` hint: - every parent was loaded by one query line, and the plugin knows the class it selected; - that line is one statement with exactly one `select(...)` call, or `.query(...)` on a session (see below), with that class as its only argument (`Order`, or `models.Order` for a module imported with `import` or `from ... import`), and the statement runs nothing else. A `session.get()`, a subquery, or a choice between queries (`a if c else b`, `or`, a comprehension) gets no patch; - that call is the statement the line runs, as it is: a `select(...)`, with only methods that keep its entities chained to it, is the first argument of `execute`, `scalars`, `scalar`, `stream` or SQLModel's `exec` on a session; a `session.query(...)` with such methods is run by `.all()`, `.first()`, `.one()` or `.one_or_none()`, or iterated (`for`, `list(...)`). A select inside a `union_all(...)`, an `exists(...)`, a subquery, a CTE, an `insert().from_select()` or another statement, one passed to a helper (`session.scalars(paginate(select(Order)))`), turned into other columns (`with_only_columns`, `with_entities`, `add_columns`), a union or a textual statement (`from_statement`), or run by something else than a session (`repository.scalars(select(Order))`) gets no patch. A session is what is named so (`session`, `self.session`, `db_session`), `db` (`db`, `self.db`), or a parameter of the function annotated with a session type that the function does not rebind: `conn: Session`, `s: orm.Session`, `conn: "AsyncSession"`, `db: Annotated[Session, Depends(get_db)]`; - or that line runs a variable on a session (`session.execute(statement)`, `session.scalars(statement)`) that the function assigns once, on an earlier line, to such a `select(...)` with only methods that keep its entities chained to it (`where`, `join`, `order_by`, `limit`, `options` and the like), and reads nowhere else. A variable that is reassigned or changed (`statement = statement.where(...)`), read again (passed to a count, for example), a parameter, a module-level name, assigned in a tuple or with `:=`, wrapped in a call (`paginate(select(Order))`), turned into a union or subquery, run by a helper (`repository.scalars(statement)`), or a `session.query()` kept in a variable gets no patch; - `select` is imported from SQLAlchemy or SQLModel, the classes (and the module in `models.Order`) are imported (or defined) in the module under their own names, the function does not rebind them, and an `.options(...)` already in the chain lists only SQLAlchemy loader calls that name each relationship as `Class.attribute`, none of them the relationship (not `*options`, an option a helper returns, or a relationship in a variable, a constant or a string: `noload(REL)`, `noload("customer")`, which may be the one the patch loads, and two loaders of one relationship conflict). A chain through another class names that class on its own (`.joinedload(Customer.country)`), so the module must import it; - a `joinedload` (a many-to-one) does not go on a statement with `with_for_update()`, `group_by()`, `having()`, `distinct()` or a prefix or suffix: its outer join would put `FOR UPDATE` on the nullable side of the join, or the joined columns outside the `GROUP BY`. A `selectinload` does; - the file is inside the rootdir, UTF-8 with `\n` or `\r\n` line ends (which the patch keeps), and was not modified after the session started, so it is the code that ran. The diff paths are relative to the rootdir (`a/app/orders.py`). When the rootdir is a subdirectory of the git repository, apply it with `git apply --directory=`, or with `patch -p1` from the rootdir. Fixes of the same file are merged into one diff; two relationships of one query become two `.options(...)` calls, which SQLAlchemy accepts. Findings left out by an ignore or the baseline get no patch. The patch is made when the test's findings are reported, from its source file: no cost per statement. Read it before you apply it, as any generated change: `joinedload` of a collection or a large row can cost more than the lazy loads it replaces. To keep the fix from regressing, put a [budget](https://maciejziel.github.io/pytest-queryguard/budgets.html) on the test: `@pytest.mark.max_queries(2)` fails it the day the count goes up again. ## 4. Or leave it out on purpose If the code is right as it is, or you cannot fix it now, leave the finding out, from the narrowest scope to the widest: - one finding in one test: `@pytest.mark.queryguard_ignore("Order.customer", function="list_orders")` (`allow_nplusone` is the same marker under its old name); - one finding in the whole suite: a line in the `queryguard_ignore` option, such as `relationship-load Order.customer function=list_orders`; - everything that exists today: a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html), so that only new findings fail; - a whole kind as a warning only: `queryguard_fail_on`; - every finding as a warning for one run: `pytest --queryguard-mode=warn`. [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html) has the details. Ignore patterns that no longer match anything are listed as stale at the end of the run, so they do not outlive the code they were written for. ## Next Once the suite is green, run it in CI ([CI and GitHub Action](https://maciejziel.github.io/pytest-queryguard/ci.html)); on a project with many existing findings, start from a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html). --- Source: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html # How detection works pytest-queryguard does not read your code. It listens to the SQL that SQLAlchemy sends while a test function runs, and applies a few rules to what it saw. ## What is measured 1. When pytest starts (unless `queryguard_mode = off`; budgets still install the listeners when a test needs them), the plugin adds class-level SQLAlchemy listeners: `before_cursor_execute` and `after_cursor_execute` on `Engine` see every SQL statement and time it, and tell a relationship lazy load or a column load from the ORM's options on its `SELECT`; `after_begin` and `after_flush` on `Session` note which `Session` a connection serves and what a flush wrote; the `load` and `refresh` instance events note which query loaded each object (see below). 2. Measurement covers only the test function body, so queries in fixture setup and teardown are not counted. unittest `setUp` and `tearDown` run inside the test call and are counted. 3. Each statement is stored with its call site: the first stack frame outside SQLAlchemy, pytest, the standard library, `site-packages` and the plugin itself. For async sessions the search continues in the parent greenlets, where the awaiting code runs. The methods of a `Session` or `AsyncSession` subclass (SQLModel's `exec()`, an application's override of `execute()`) are passed over too: they are part of the session, and the line that called the session is the call site. Only when no other frame of the application is on the stack is the session method the call site. 4. After the test, the stored events are checked against the budget and the rules below. A test stores at most `queryguard_max_events` statements; past that they are only counted, and the report says so. The findings are then filtered by the `queryguard_ignore` option, the `queryguard_ignore` marker and the [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html), and reported as a failure, a `QueryGuardWarning` or a line in the [SARIF file](https://maciejziel.github.io/pytest-queryguard/sarif.html), depending on `queryguard_mode` and `queryguard_fail_on`. The N+1s of the test code itself are left out by default (see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)). ## The rules Every rule produces a finding with a kind, a label, a call site and a hint. In short, the kinds and what they do by default: | Kind | Reports | Default | |---|---|---| | [`relationship-load`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load) | one relationship lazy-loaded for 2 or more parents | fails | | [`repeated-statement`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#repeated-statement) | one SELECT shape run 5 or more times | fails | | [`column-load`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#column-load) | 5 or more objects of one class reloading columns (deferred, expired, subclass) | fails | | [`cartesian-load`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#cartesian-load) | one SELECT that joins two collections side by side | warns (`queryguard_cartesian_load`) | | [`write-loop`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#write-loop) | one INSERT, UPDATE or DELETE per row | off (`queryguard_write_loop_threshold`) | | [`missing-index`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#missing-index) | a SELECT no index can serve | off (`--queryguard-index-check`) | | [`unused-eager-load`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#unused-eager-load-experimental) | an eager-loaded relationship the test never reads | off, experimental | | [`unused-columns`](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#unused-columns-experimental) | wide rows of which the test reads few columns | off, experimental | "Fails" is in the default `queryguard_mode = fail`; in `warn` mode every kind only warns, and [budgets](https://maciejziel.github.io/pytest-queryguard/budgets.html) fail either way. ### relationship-load One relationship (for example `Order.customer`) is lazy-loaded for at least `queryguard_relationship_threshold` (default 2) different parent objects that one query line loaded (see "Where the parents were loaded" below). The label is the relationship. The hint is `joinedload` for a many-to-one or one-to-one relationship and `selectinload` for a collection. The rule counts distinct parent objects, not statements, so it is independent of how SQLAlchemy batches the loads. The parents are grouped by the line of the query that loaded them, as strict mode groups them: a loop over the rows of one query is an N+1, two single-object lookups that each read the relationship (`session.get(Order, 1).customer`, then `session.get(Order, 2).customer`) are not. Lookups made one by one at the same line (`for id in ids: get_order(id).customer`) count together. With Django, the parents of one query line are also told apart by the lines that called the read: a helper that gets one object and reads its relationship, called once from each of two lines, is two lookups, while the same helper called in a loop is an N+1. The finding counts the lazy loads of the groups that reach the threshold; when several do, it names the first query line and how many others. When the query of a parent is unknown (objects the test created that a query or `session.get()` handed back without reading their row, objects loaded before the test body, objects that two queries read), the plugin cannot tell which query it belongs to: such parents are grouped by the line that read the relationship instead. A loop reads it at one line; code that creates three objects and reads each one's relationship on a line of its own (SQLModel's tutorials) is no N+1. A parent of unknown origin also counts for every query line's group whose parents were read at the same line, so an unknown origin never hides a loop. A query line whose lazy loads all ran inside an `ignore("relationship-load")` block is left out of the finding, the other lines are still reported. The grouping has a cost: a loop over the rows of several queries that return one row each (`for order in [*open_orders, *closed_orders]` with one order of each) has a single parent per query line and is not reported; give the test two rows for one of the queries, as for any N+1 test. #### Refreshing an object with an eager relationship `session.refresh(obj)`, `session.refresh(obj, ["children"])` and the reload of an expired object do not run a mapped `lazy="selectin"` or `lazy="subquery"` loader the way a query does. SQLAlchemy loads such a collection for that one object through its immediate loader, with the parent attached, which is also how a lazy load looks. The plugin tells the two apart: while the loader runs for a refresh (the outer load has a refresh state), the statement keeps the relationship label but is not counted as a lazy load, because `selectinload` is already the mapped strategy. Only the loader's own query is exempt: its parent must be the refreshed object and its relationship the one the loader loads. An `immediateload()` option on a plain query, every `lazy="select"` access, and a lazy load that user code runs while the loader builds the children (a `@reconstructor` or a `load` event reading a `lazy="select"` relationship) are still lazy loads. A loop of refreshes is its own finding, a column-load (see below), not a relationship-load: `for obj in objs: session.refresh(obj)` is reported once the column-load threshold (default 5) is reached, and the collection queries it runs are never a repeated-statement finding. A refresh that reads back the object the flush before it wrote is not counted at all (see "Refresh after a write" under column-load). The plugin tells the immediate loader's statement by the outer query's context, which SQLAlchemy hands to it (the private execution option `sa_top_level_orm_context`, the same from 2.0.13 to 2.1): for a refresh it names the object refreshed. If a SQLAlchemy release stops passing it, these loads count as lazy loads again, as before this rule: a possible false positive, never a missed lazy load and never an error. #### Where the parents were loaded The report names the query that loaded the parent objects (`parents loaded at`) and chains the loader hint from it. The call site of each `SELECT` is kept with its result, and while the ORM turns its rows into objects the `load` instance event (and `refresh`, for an object the `Session` already had whose row the query reads again) stores that call site and the object's load path (`Order -> Order.customer -> Customer`) on the object's state. The call site is looked up once per query, not per row. Objects of a `selectinload` or `subqueryload` query and of a lazy load inherit the site of the query they were loaded for. A lazy load later reads them from its parent, and the finding uses them only when all its loads agree: a single site (or, when the parents of several query lines each reach the threshold, the first one and how many others), and a single load path that can be written as `select(Root).options(loader(A.b).loader(B.c))` (no aliased class or `of_type()`). Otherwise the line is left out and the hint names the relationship's own class, as without the information. An object whose row two queries from different places read gets no origin; one that a query returns from the identity map without reading its row fires no event, so it keeps the query that loaded it. Origins are kept per measurement: an object loaded before the test body (or before a `record_queries()` block) has none there. A block that starts or ends, in the test or in another thread, does not take the test's origins away. The in-app mode does not record origins and prints the earlier hint. #### How a lazy load's statement is attributed The ORM keeps what a `SELECT` is for in the options of that execution: the parent object of a lazy load, the object of a column load and the relationship path of a loader. The plugin reads them in `before_cursor_execute`, from the statement itself, so nothing else that runs in between can take or clear them: the autoflush before a lazy load, the `Session`'s begin step (the engine's `begin` event and `after_begin` listeners, such as SQLAlchemy's pysqlite `BEGIN` recipe), statements of another `Session` on the same connection (a second `Session` joined to the external connection of a "test in a transaction" fixture), and other asyncio tasks or threads. A lazy load that never reaches the database (a `do_orm_execute` listener of yours answers it from a cache) is not counted. These options are private to SQLAlchemy; the plugin reads them in one place and is tested from SQLAlchemy 2.0.13 to 2.1. ### repeated-statement One `SELECT` runs at least `queryguard_repeat_threshold` (default 5) times in one test. Statements are compared after normalization: whitespace is collapsed, literals and parameter placeholders become `?`, and `IN (...)` lists of any length are one shape. Statements already reported as a relationship or column load are not counted again, and `INSERT`, `UPDATE` and `DELETE` are never counted by this rule, nor are transaction-control statements: `BEGIN`, `COMMIT`, `ROLLBACK` (also `ROLLBACK TO SAVEPOINT`), `SAVEPOINT`, `RELEASE`, `START TRANSACTION` and `SET TRANSACTION`. A loop that commits on each pass runs one `BEGIN` and one `COMMIT` per pass, for example with SQLAlchemy's pysqlite `BEGIN` recipe, and that is not a query to batch. Budgets (`max_queries`) still count these statements. Other `SET` statements (`SET search_path`, `SET LOCAL ...`) are counted like any statement, and so is a `BEGIN` that opens a block rather than a transaction (`BEGIN load_order(:id); END;`). A loop that opens a `SAVEPOINT` for each row still shows its `INSERT`s to the [write-loop](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#write-loop) rule. Pagination and chunked `IN` loads are not counted either, when their parameters show it (see below). The label is the normalized statement. This rule sees Core and `text()` statements as well as ORM ones. Schema reflection is not counted either, by this rule or by the small-repeat rule: SQLAlchemy's `MetaData.reflect()`, `Inspector.has_table()` and `metadata.create_all()` run one catalog query per table, and Alembic's autogenerate and version-table checks do the same, so a loop over them is no N+1 the application could batch. A statement is skipped when it starts with `PRAGMA`, `SHOW`, `DESCRIBE` or `DESC` (MySQL and MariaDB), reads `sqlite_master`, `sqlite_schema`, `sqlite_temp_master` or `sqlite_temp_schema` (also as `main.` or `temp.`), or reads anything in the `pg_catalog` or `information_schema` schema. It is matched on the normalized text, so a string value such as `'sqlite_master'` does not count, nor does a name in an SQL comment, or a CTE or table alias the statement itself names `sqlite_master`, `pg_catalog` or `information_schema`. A statement that joins an application table with a real catalog is skipped too. Not skipped: PostgreSQL catalog tables read without the schema name (`pg_class` found through the search path). These statements still count for `max_queries` and appear in the report. With `queryguard_small_repeat_threshold` set (off by default, for example `2`), a statement that ran at least that many times but fewer than the repeat threshold is reported too, if all of these hold: every run came from the same source line, every run had different parameters, the statement is not a write or transaction control, and it is not pagination (`OFFSET`, or `LIMIT` with a `>` or `<` condition on a parameter) or a chunked `IN` load as described below. #### Pagination and chunks Walking through a result page by page, and loading a long list of keys in slices, run one statement shape many times on purpose. Both rules leave such runs alone when the statements and their bound parameters show it. Each parameter is classified by the SQL just before it: after `OFFSET` it is the offset, after `LIMIT` (or `FETCH FIRST`, `TOP`) the page size, after `<`, `<=`, `>` or `>=` a range bound, inside an `IN (...)` list a list member, and anything else a plain value. Literal `LIMIT 4 OFFSET 8` values count as page size and offset. The values come from the parameters the driver got, by position (`?`, `%s`, `$1`) or by name (`%(name)s`, `:name`). The runs of one shape are **pagination** when all of these hold: - the statement has `OFFSET`, or `LIMIT` with a range bound; - the plain values, the `IN` lists and the page size are the same in every run: only the cursor (the offsets and range bounds) changes. A loop over items changes a plain value (`WHERE customer_id = ?`), so the first page of each customer's orders is still reported; - the page size, when it is known, is more than one row. `LIMIT 1 OFFSET n` reads a table one row per statement and is still reported, which answers the concern in [#60](https://github.com/MaciejZiel/pytest-queryguard/issues/60); - the cursor moves the same way (up or down) from run to run and never repeats, and an offset moves by at least the page size, so pages do not overlap; - a keyset bound is an integer and moves by at least the page size: the next cursor is the last key of a full page (only the step after the last, partly filled page may be shorter, and it ends the walk). A loop that passes each row's own key (`WHERE id > :row_id LIMIT 3` for every row) moves it by one row and is reported. String and date bounds cannot be measured, so their walks are reported as before; - the walk may start again from its first cursor once (a test that reads the same list twice). The same walk run three or more times is a loop-invariant query inside a loop and is reported, and so is a restart anywhere else. The runs are a **chunked `IN` load** when all of these hold: - one `IN` list changes from run to run and everything else is the same; - the lists share no value: together they partition one list of keys; - every list has the same length, at least 50 values, except one shorter list (the remainder, in any position). The minimum of 50 is there because per-item lists are short: the two addresses of an order, a customer's ten orders. A helper called with each customer's own orders sends equal-sized lists that share no value, which only their length tells apart from chunks. Batch sizes of loaders and ORMs are larger (`selectinload` uses 500). A list of one id per run is reported. What these rules cannot see, and so still report: a polling loop and a loop-invariant query, which both repeat one statement with the same parameters (the first is fine, the second is a bug, and the statements are the same); composite keyset conditions such as `a < ? OR (a = ? AND b < ?)`, where the bound is also a plain value; keyset walks on a string or date column; MySQL's `LIMIT offset, count`; `IN` lists written as literals; and two chunked loads of the same keys in one test (the lists overlap). A parameter that cannot be read (an unknown placeholder style, values that do not compare) means the statements are reported as before. ### column-load At least `queryguard_column_load_threshold` (default 5) instances of one class each go back to the database for columns they already have a row for. There are three causes, and the report tells them apart: a deferred column (`deferred()`, `defer()`, `load_only()`), where the hint is `undefer(Model.column)`; attributes expired by `commit()`, `expire()` or `expire_all()`, where the hint is `expire_on_commit=False` (a `refresh()` in a loop gets its own hint); and the columns of a subclass that a query of its base class left out (joined- or single-table inheritance: `select(Employee)` does not select `Engineer.language`), where the hint is `selectin_polymorphic` or `polymorphic_load="selectin"` for a table of their own, and `with_polymorphic` or `polymorphic_load="inline"` for single-table inheritance. SQLAlchemy marks those subclass columns as expired, so the plugin tells them from an `expire()` by the class each instance was loaded as: a base class of it that maps none of the columns. The hint names that class. A `session.expire(obj, [...])` of subclass columns of an object loaded through a base-class query gets the subclass hint too. The label is the class and its deferred columns (`Book.summary`) or the class and the cause (`Book (expired)`, `Book (refresh)`, `Engineer (polymorphic)`). `session.refresh(obj, ["name"])` is a refresh too, although it expires the names before loading them. #### Refresh after a write A repository layer often refreshes every object it creates or updates, to read server defaults and `onupdate` values (advanced-alchemy's `auto_refresh`, on by default, does it after each `add()` and `update()`). Each of those refreshes is asked for once per write, so a test that creates ten rows through such a repository is not a loop of reads. A `session.refresh()` of an object that the latest flush of its Session inserted, or changed (a column or a collection, after a net change), is therefore not counted, for one object per class and flush; its statement still carries the column-load label, so it is not a repeated statement either. A loop that writes one object, flushes and refreshes it in each iteration is therefore not a column-load finding; its INSERT or UPDATE statements are what the opt-in [write-loop](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#write-loop) rule reports. Still counted: - a refresh of an object that was only read (`for obj in query: session.refresh(obj)`); - refreshing every row of one bulk insert (`add_all()`, one flush, a refresh per row): the first refresh is let through, the others count; - a second refresh of the same write, and a refresh of an object an older flush wrote; - a refresh of an object that was in `session.dirty` but had no net change (an attribute set to its own value), since the flush wrote nothing for it; - attributes reloaded after `commit()` or `expire()` without a refresh (the `expired` cause). ### write-loop Off by default. With `queryguard_write_loop_threshold` set (for example `5`), the same `INSERT`, `UPDATE` or `DELETE` shape, one row per statement, run that many times from one source line is reported, with a hint to write the rows together (`session.add_all()` and one flush, or `session.execute(insert(Model), rows)`). `executemany` and multi-row `VALUES` statements are already batched and never counted. The statements of one ORM flush count as one: on a dialect without `insertmanyvalues`, `session.add_all()` and one `flush()` still send one `INSERT` per row, and that is not a loop in your code. A `flush()` or `commit()` per row, which is, is reported. The flush is recognized from the call stack (SQLAlchemy's `Session._flush`); if a future SQLAlchemy release changes that, such a flush is reported again until the detection is updated. ### What the count rules count together The relationship, repeated-statement, column-load and write-loop rules count over a scope. By default (`queryguard_scope = test`) the scope is the whole test, except that a `Session` (or connection checkout) begun from application lines that no other `Session` of the test began from is counted on its own: a store method that opens a `Session` per call, called on separate lines, is not a loop. With `session`, each SQLAlchemy `Session`, or each connection checkout for statements no `Session` ran, is counted on its own, and a finding needs one scope to reach the threshold. See [Tests with several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html#sessions-begun-on-separate-lines). #### Calls on separate lines Within a scope, the rules also tell a loop from calls on separate lines. Each statement is stored with its call path: the line of every frame of your code on the stack, up to the test function (a recursive function counts at its innermost frame, so every depth of a recursion has the same path). The passes of a loop run a statement from the same path; code that calls the same helper on six lines of its own, or a test that sends six requests one after the other through one shared `Session`, runs it from six paths. So: - a statement whose call path no other run of it has is counted on its own, and never reaches a threshold alone; - the runs whose path repeats count together, whatever path each has, so a loop whose passes take two paths (an `if`/`else` in the loop body) is not split in two; - so do the runs whose paths part at one line that calls different functions directly: a loop whose passes each call a method of their own (five items of five classes, a handler looked up in a dict per item) calls them all from the line of the loop. Paths that part at different lines of one function are calls on separate lines, and so are a request hook and a view that a framework calls for one request: the framework's frames lie between the test line and each of them. A function that counts six statuses with one helper, one call per line, runs a fixed number of queries whatever the data: no repeated-statement finding. The same lookup in a loop is reported as before. A loop shorter than the threshold next to calls on separate lines is not reported: four passes and a fifth run on a line of its own are four runs of the loop. For a lazy load and a column load the path is only the lines of the test code that called the application (see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)): a loop over objects that are already in the `Session` lazy-loads some of them only, so a single lazy load at a line of the application can still be a pass of a loop. Two requests the test sends from separate lines are not: each lazy-loads the customer of its own order, and the two loads are not an N+1. Lazy loads that test code runs itself (no application frame) are not split. In strict mode the lazy loads of all test lines count together, as strict mode decides at the load, before the later loads show which lines call the application again. Not split: requests that the application handles in another thread (Starlette's `TestClient`), whose stack does not reach the test, and the statements of a test past `queryguard_max_events`. ### Test code A test exercises the application, and also runs code of its own: factories that create its rows, helpers that build the expected values, a test client that sends requests. That code never runs in production, so an N+1 in it is not a defect of the application, and by default (`queryguard_test_code = off`) it does not fail the test. A file is test code when it is: - a Python test module that pytest collected (its test functions, its helpers, a unittest `setUp`); - a `conftest.py`; - below a directory named `tests` or `test` inside pytest's rootdir (`tests/factories.py`, `tests/utils/client.py`). When the rootdir is itself such a directory (its `pytest.ini` is the configuration, or pytest runs from inside it with no configuration file), every file below it is test code, when the directory above it holds `.git`, `pyproject.toml`, `setup.py`, `setup.cfg` or `tox.ini` and the rootdir holds none of them (a repository checked out into a directory named `test` is not test code); - a module that defines a [factory_boy](https://factoryboy.readthedocs.io/) or [polyfactory](https://polyfactory.litestar.dev/) factory class, wherever it lives (`myapp/testing/factories.py`). A statement, lazy load or column load is the test code's when every frame of your code on its stack is test code, and no installed package other than a test tool (factory_boy, polyfactory, model_bakery, mixer, django-dynamic-fixture, Faker, pytest plugins) or a `Session` subclass (SQLModel's `Session.exec()`) lies between the test and the statement: an application installed into `site-packages` (`pip install .`, tox) has no frame of "your code", so a statement it runs for the test stays the application's. One frame of the application is enough to make it the application's: a loop in the application that a test helper calls, a request handler that a test client in `conftest.py` calls, a model event that a factory's flush fires. Those are reported as before. The count rules then run twice: once on the application's statements and loads, whose findings fail the test as usual, and once on those of the test code. With `queryguard_test_code = off` the second findings are only counted, in a section at the end of the run that names five of the tests, in node id order: ``` ============================ queryguard: test code ============================= 422 N+1 findings in test code left out (299 tests): the statements ran only in test modules, conftest.py, factories or helpers under tests/, or once in each call that a loop of the test made into the application. To see them: pytest -o queryguard_test_code=warn, or set queryguard_test_code = warn (or fail) in the pytest configuration. Why: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code tests/test_accounts.py::test_create_account tests/test_accounts.py::test_delete_account tests/test_billing.py::test_invoice_lines tests/test_billing.py::test_refund tests/test_orders.py::test_list_orders and 294 more ``` `warn` reports them as a `QueryGuardWarning`, and `fail` counts the statements of the test code with the application's, as 0.9.0 and earlier did. The ignore patterns, markers and blocks match them in every mode, so a pattern written for them is not stale. With `off` they are not in the SARIF file or the JSON file; a baseline entry for one still counts as matched (it is not stale), and `--queryguard-update-baseline` keeps it, but adds none that is not there yet. Strict mode does not raise at a lazy load of the test code with `off` or `warn`. Why a factory counts as test code: a factory's lookup per object (a role looked up by name for every user it creates) slows the suite, but it is not in the application, and fixing it does not change what production does. The same goes for a helper that builds the expected values with lazy loads. Where a factory or a helper is shared with production code, or the application lives below a `tests` directory, set `queryguard_test_code = fail`. #### Loops of the test A loop in the test that calls the application once per pass (a case per pass, a page per request, an object per `create()` or factory call) makes the application run its statements once per pass: in production each call is a request or a job of its own. Each statement and load records the call of the application that test code made (the frame the test's line called, past the frames of test tools such as factory_boy's `create_batch()`). When every call ran a statement once (a lazy load: read the relationship of one object), and more than one call took part, the repetition is the test code's: it follows `queryguard_test_code` as above, and is counted in the same section with `off`. A call that ran the statement twice or more is a loop (or a repetition) of the application, and the finding stays the application's, whatever the test around it does. ```python def test_order_pages(session): for order_id in ids: # the test's loop order_page(session, order_id) # one order and its customer: test code's def test_order_lists(session): for customer_id in ids: order_list(session, customer_id) # a lazy load per order inside: reported ``` `fail` counts them with the application's, as 1.0 did. Strict mode decides at the lazy load, before the later calls are known, and still raises at the second pass. What it cannot tell apart: an application function defined in a test module (the shortest example in a bug report) is test code; move it to a module of its own, or set `queryguard_test_code = fail`. ### unused-eager-load (experimental) Off by default. See [Unused eager loads](https://maciejziel.github.io/pytest-queryguard/unused-eager-load.html). ### unused-columns (experimental) Off by default. See [Unused columns](https://maciejziel.github.io/pytest-queryguard/unused-columns.html). ### cartesian-load One query, so no count rule and no budget sees it: ```python select(Customer).options(joinedload(Customer.orders), joinedload(Customer.notes)) ``` The SELECT joins both collections to the customer, so each customer comes back once per pair of an order and a note: 20 orders and 20 notes are 400 rows for one customer, and the ORM folds them back into 20 + 20 objects. The rows grow as the product of the collections, which is slow and memory-heavy long before a test notices. The rule reads the loader options of each top-level ORM SELECT, and the loader strategies of the mapping (`relationship(lazy="joined")`, or the old `lazy=False`) of each entity it loads. It reports a statement in which two collections are joined side by side: - **side by side**: neither is on the path of the other. `joinedload(Customer.orders).joinedload(Order.items)` is a chain whose rows grow with the number of items, not a product, and is not reported; `joinedload(Order.customer).joinedload(Customer.notes)` with `joinedload(Order.items)` is (a scalar on the way does not multiply, the two collections still do). - **in one statement**: a `selectinload` or `subqueryload` on the way starts a SELECT of its own, so `selectinload(Customer.orders).joinedload(Order.items)` and `...joinedload(Order.tags)` are a product inside that second SELECT and are reported, while `joinedload(Customer.orders)` with `selectinload(Customer.notes)` is not. - a `defaultload()` or `lazyload()` step runs the relationship's own loader, usually a lazy load with a SELECT of its own, so `defaultload(Customer.orders).joinedload(Order.items)` with `...joinedload(Order.tags)` is a product inside each lazy load and is reported. - `contains_eager()` is left out: a query that joins on purpose to filter chose its rows. So are wildcards (`joinedload("*")`) and a select of several entities whose collections belong to different entities. - With a chain next to a collection, `joinedload(Customer.orders).joinedload(Order.items)` and `joinedload(Customer.notes)`, the product is orders x notes: the finding names the topmost collection of each branch. The label names the collections, `Customer.notes + Customer.orders`; the fix keeps one `joinedload` and turns the others into `selectinload`, one more query each and no repeated rows: ``` Customer.notes and Customer.orders were joined into one query side by side, once first at app/customers.py:12 in list_customers kind: cartesian-load label: Customer.notes + Customer.orders each row repeats per pair of their items: the rows grow as their product fix: load all but one of them with selectinload, e.g. select(Customer).options(joinedload(Customer.notes), selectinload(Customer.orders)) (one more query for each, and no repeated rows) ``` - A strategy of the mapping counts as SQLAlchemy uses it: where no option of the query names the relationship and no wildcard (`lazyload("*")`, `Load(A).raiseload("*")`) covers it, and below an eager step only. Two collections with `lazy="joined"` are reported on every `select()` of the class, `session.get()` included; a collection with `lazy="joined"` next to a `joinedload()` option is reported too. A relationship that loads lazily is not followed (its children are joined only if it is read), and a self-referential relationship is followed only as deep as its `join_depth`. A `select()` of columns (`select(A.id)`), `from_statement()` and a `Query` with `enable_eagerloads(False)` load no instances and are left out. It warns by default (`queryguard_cartesian_load = warn`); `fail` fails the test in `fail` mode, `off` turns the check off. The rule does not count rows: it cannot know that two collections stay small, such as a user's two roles and two e-mail addresses joined into one login query, and reports them like two that grow. A test database rarely holds as many rows as production, so a rule that counted them would miss the products that matter. When a product stays small by design, keep the joins and silence that one finding: `queryguard_ignore = cartesian-load User.emails + User.roles` in the configuration, or `with ignore("cartesian-load"):` around the query (see [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html)). A product on the mapping is fixed on the query (`selectinload()` of all but one of the collections) or on the mapping (`lazy="selectin"`). ### missing-index Off by default; PostgreSQL 16 and newer, SQLite, MySQL and MariaDB. See the [PostgreSQL](https://maciejziel.github.io/pytest-queryguard/index-check.html), [SQLite](https://maciejziel.github.io/pytest-queryguard/index-check-sqlite.html) and [MySQL and MariaDB](https://maciejziel.github.io/pytest-queryguard/index-check-mysql.html) pages. ## Thresholds and why | Option | Default | Why this value | |---|---|---| | `queryguard_relationship_threshold` | 2 | One lazy load of a relationship is normal. Two parents each loading it is the smallest case of a loop over rows, and the rule has to work on test databases with a few rows. Raise it if two is too strict for your code (see the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html)). | | `queryguard_repeat_threshold` | 5 | A few runs of one statement are often a deliberate small batch, so the default is higher than for relationships. | | `queryguard_small_repeat_threshold` | 0 (off) | Catches loops of two to four runs; off because it can report small legitimate repetition, so it is a choice. | | `queryguard_column_load_threshold` | 5 | Touching a few objects after a `commit()` is ordinary test code; the limit is as high as the repeat rule's. | | `queryguard_write_loop_threshold` | 0 (off) | Row-by-row writes are normal in many tests, so the kind is opt-in. | The defaults are choices, not measurements. Every threshold is an ini option. ## What the rules cannot see See [Limitations](https://maciejziel.github.io/pytest-queryguard/limitations.html). In short: only SQLAlchemy statements are seen, only inside the test body, and a rule says that a pattern happened, not that production would be slow. --- Source: https://maciejziel.github.io/pytest-queryguard/n-plus-one-sqlalchemy-tests.html # Detect N+1 queries in SQLAlchemy tests Install pytest-queryguard and run your tests as usual. Every test is checked: when the code it calls lazy-loads a relationship once per row, or sends the same statement in a loop, the test fails and the report names the line and the eager load that fixes it. There is no fixture, marker or setting to add. ```bash pip install pytest-queryguard ``` It needs Python 3.10 or newer, pytest 8 or newer and SQLAlchemy 2.0.13 or newer, and works with sync and async sessions, 2.0-style `select()`, the legacy `Query` API and Core. ## Example The models and the `session` fixture are those of [Getting started](https://maciejziel.github.io/pytest-queryguard/getting-started.html#a-first-test): 50 orders, each belonging to a customer, in an in-memory SQLite database. The function lists the orders with their customer's name. `app/orders.py`: ```python from sqlalchemy import select from sqlalchemy.orm import Session from app.models import Order def list_orders(session: Session) -> list[dict[str, object]]: rows = [] for order in session.scalars(select(Order)).all(): rows.append({"id": order.id, "customer": order.customer.name}) return rows ``` `tests/test_order_list.py`: ```python from app.orders import list_orders def test_list_orders(session): assert len(list_orders(session)) == 50 ``` The test passes without the plugin. With it, `pytest` fails it: ``` queryguard: N+1 detected Order.customer was lazy-loaded 50 times first at app/orders.py:10 in list_orders called from tests/test_order_list.py:5 in test_list_orders parents loaded at app/orders.py:9 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` The loop sent 51 statements: one for the orders, then one per customer. The fix loads the customers with the orders. `app/orders_fixed.py`: ```python from sqlalchemy import select from sqlalchemy.orm import Session, joinedload from app.models import Order def list_orders(session: Session) -> list[dict[str, object]]: rows = [] for order in session.scalars(select(Order).options(joinedload(Order.customer))): rows.append({"id": order.id, "customer": order.customer.name}) return rows ``` The same test against it passes, and with `max_queries(1)` it also checks that the function sends a single statement. `tests/test_order_list_fixed.py`: ```python import pytest from app.orders_fixed import list_orders @pytest.mark.max_queries(1) def test_list_orders(session): assert len(list_orders(session)) == 50 ``` The test database needs at least two parent rows for an N+1 to show: by default a relationship lazy-loaded by two parents from the same query is reported (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load)). A repeated statement is reported from five runs. ## What else it reports - the same `SELECT` sent in a loop, such as `session.get()` per id or a Core or `text()` query per row ([repeated statements](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#repeated-statement)); - a test that sends more statements than a limit you set ([query budgets](https://maciejziel.github.io/pytest-queryguard/budgets.html), or [Assert the number of SQL queries](https://maciejziel.github.io/pytest-queryguard/count-queries-sqlalchemy-tests.html)); - when you turn them on, `INSERT`, `UPDATE` or `DELETE` sent once per row ([write loops](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#write-loop)) and queries with no index to use on PostgreSQL, SQLite, MySQL and MariaDB ([index check](https://maciejziel.github.io/pytest-queryguard/index-check.html)). Loops written in the test itself or in its fixtures are not reported by default: they never run in production (see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)). ## Next - [A test failed: now what](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html): check the finding, fix it or leave it out on purpose. - Recipes for [FastAPI](https://maciejziel.github.io/pytest-queryguard/recipes-fastapi.html), [Flask-SQLAlchemy](https://maciejziel.github.io/pytest-queryguard/recipes-flask-sqlalchemy.html), [SQLModel](https://maciejziel.github.io/pytest-queryguard/recipes-sqlmodel.html) and [Litestar](https://maciejziel.github.io/pytest-queryguard/recipes-litestar.html). - An existing suite with many findings: [Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) and [Adopting on a legacy codebase](https://maciejziel.github.io/pytest-queryguard/recipes-legacy.html). - Coming from nplusone, which does not see SQLAlchemy 2.0-style queries and does not import on 2.1: [Migrating from nplusone](https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html). --- Source: https://maciejziel.github.io/pytest-queryguard/n-plus-one-django-tests.html # Find N+1 queries in Django tests with pytest If your Django tests already run with pytest-django, install pytest-queryguard next to it. Every test is then checked: when the code it calls reads a foreign key, a reverse relation or a many-to-many relation once per object, the test fails and the report names the line and the `select_related()` or `prefetch_related()` that fixes it. Nothing goes into `INSTALLED_APPS`, `MIDDLEWARE` or your settings. ```bash pip install "pytest-queryguard[django]" pytest-django ``` It needs Django 5.2, 6.0 or 6.1. Since 1.1.0 the Django support is no longer experimental: its findings follow the [stability policy](https://maciejziel.github.io/pytest-queryguard/stability.html#what-is-public) like the rest of the plugin. ## Example A model with a foreign key: ```python # library/models.py from django.db import models class Author(models.Model): name = models.CharField(max_length=100) class Book(models.Model): title = models.CharField(max_length=200) author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="books") ``` a function that reads the author of each book: ```python # library/catalog.py from library.models import Book def book_lines(): return [f"{book.title} by {book.author.name}" for book in Book.objects.all()] ``` and a test that calls it: ```python # tests/test_books.py import pytest from library.catalog import book_lines from library.models import Author, Book @pytest.fixture def books(db): for i in range(3): author = Author.objects.create(name=f"author {i}") Book.objects.create(title=f"book {i}", author=author) def test_book_lines(books): assert len(book_lines()) == 3 ``` The test passes without the plugin. With it, it fails at the end of the test with: ```text queryguard: N+1 detected Book.author was lazy-loaded 3 times first at library/catalog.py:6 in book_lines called from tests/test_books.py:16 in test_book_lines parents loaded at library/catalog.py:6 in book_lines kind: relationship-load label: Book.author docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT "library_author"."id", "library_author"."name" FROM "library_author" WHERE "library_author"."id" = %s LIMIT 21 fix: load it with the parent query, e.g. Book.objects.select_related("author") or, on Django 6.1+, .fetch_mode(models.FETCH_PEERS) on that query ``` With `Book.objects.select_related("author")` the test passes. The fixture's writes are not counted: only the test function's body is. ## Compared with `django_assert_num_queries` pytest-django's `django_assert_num_queries` and Django's `assertNumQueries` check a number you choose, in the tests where you write them. pytest-queryguard needs no number and checks every test. It also reports the same `SELECT` run five or more times (`get()` or `exists()` per item), and its `max_queries` marker and `record_queries()` give you counts when you want them ([Django: Collecting queries without failing the test](https://maciejziel.github.io/pytest-queryguard/django.html#collecting-queries-without-failing-the-test)). ## Next - [Django](https://maciejziel.github.io/pytest-queryguard/django.html): every relation it checks, what it leaves out, its limits, and its accuracy against django-zeal and nplusone. - [A test failed: now what](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html): check the finding, fix it or leave it out on purpose. - [The query count must not grow with N](https://maciejziel.github.io/pytest-queryguard/recipes-query-count-scaling.html): a scaling test with 1, 10 and 50 rows, for Django too. - An existing suite with many findings: [Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html). --- Source: https://maciejziel.github.io/pytest-queryguard/count-queries-sqlalchemy-tests.html # Assert the number of SQL queries in a SQLAlchemy test SQLAlchemy has no `assertNumQueries` like Django's test case. With pytest-queryguard installed, put `@pytest.mark.max_queries(n)` on a test to fail it when its body sends more than `n` statements, or wrap a block in `record_queries()` and assert on the count and the SQL yourself. ```bash pip install pytest-queryguard ``` ## Example The models, the `session` fixture and the functions are those of [Getting started](https://maciejziel.github.io/pytest-queryguard/getting-started.html#a-first-test): 50 orders, each with a customer. `list_orders` in `app/orders_fixed.py` loads the customers with `joinedload`; `rename_customers` in `app/customers.py` loads and flushes one customer at a time. `tests/test_query_count.py`: ```python import pytest from app.customers import rename_customers from app.orders_fixed import list_orders from pytest_queryguard import record_queries @pytest.mark.max_queries(1) def test_list_orders_runs_one_query(session): assert len(list_orders(session)) == 50 def test_list_orders_reads_the_customers_in_the_same_query(session): with record_queries() as log: list_orders(session) assert log.count == 1 assert "JOIN customer" in log.queries[0].sql @pytest.mark.max_queries(2) def test_rename_two_customers(session): rename_customers(session, {1: "Ada", 2: "Grace"}) ``` The first two tests pass. The third fails and lists every statement with the line that sent it: ``` queryguard: expected at most 2 queries, got 4 1. SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/customers.py:15 in rename_customers) 2. UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) 3. SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/customers.py:15 in rename_customers) 4. UPDATE customer SET name=? WHERE customer.id = ? (app/customers.py:16 in rename_customers) ``` The marker counts the statements of the test body, writes included, and not those of its fixtures. `record_queries()` counts the statements of its block, from any thread, so it also works around a `TestClient` request; join worker threads of your own before you read the count. ## Choosing the number A fixed number breaks when the code legitimately changes. Two ways to avoid picking one by hand: - record today's count of every test in a budget file and fail only when a count grows: [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file); - run the code with 1, 10 and 50 rows and assert the count stays the same: [The query count must not grow with N](https://maciejziel.github.io/pytest-queryguard/recipes-query-count-scaling.html). Without any marker, every test is still checked for N+1 queries: [Detect N+1 queries in SQLAlchemy tests](https://maciejziel.github.io/pytest-queryguard/n-plus-one-sqlalchemy-tests.html). ## Next - [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html): the marker's options, a default budget for every test, and time limits. - [Reading the queries](https://maciejziel.github.io/pytest-queryguard/python-api.html): everything `record_queries()` returns, including the call site and duration of each statement. - [Budgets for hot endpoints](https://maciejziel.github.io/pytest-queryguard/recipes-budgets.html): where a budget pays off. --- Source: https://maciejziel.github.io/pytest-queryguard/comparison.html # 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. **In short:** of the SQLAlchemy tools in the matrix, pytest-queryguard is the only one that fails tests with no marker, option or fixture, and the only one with a missing-index check beyond PostgreSQL (SQLite, MySQL and MariaDB). It reports Core and `text()` loops as well as lazy loads, lists every statement with its call site when a budget fails, and has a baseline and SARIF for adoption. These are the features of the current release; the [measured runs](https://maciejziel.github.io/pytest-queryguard/comparison.html#what-i-measured) are of the dated versions named below. queryspy is the closest alternative, with its own middleware and panel; pytest-querycount writes budgets into your tests; for Django, django-zeal is the established tool and pytest-queryguard covers it too ([Django](https://maciejziel.github.io/pytest-queryguard/django.html), no longer experimental since 1.1.0). The [matrix](https://maciejziel.github.io/pytest-queryguard/comparison.html#feature-matrix), [where the others are ahead](https://maciejziel.github.io/pytest-queryguard/comparison.html#where-the-others-are-ahead) and [choosing](https://maciejziel.github.io/pytest-queryguard/comparison.html#choosing) have the details. - 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, and describe 0.4.0 (2026-10-14). 0.4.1 changed only the database time of statements that finish in another thread, which no row below measures, and 0.5.0 added the in-application mode without changing the plugin. - Versions re-checked on **2026-11-05** on PyPI: queryspy 0.6.0 and django-zeal 2.3.0 had been released since. Their changelogs list no change to a cell of the matrix except the one marked "since 2.3.0": queryspy 0.5.1 and 0.6.0 change only the supported Python versions (0.6.0 drops 3.10), and django-zeal 2.3.0 adds an opt-in check for unused `zeal_ignore` blocks and fixes in its N+1 detection. The cells marked (v) were verified on queryspy 0.5.0 and were not run again on 0.6.0. - The [head-to-head](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions) numbers (accuracy and overhead of pytest-queryguard 1.0.0rc1, queryspy 0.6.0, pytest-querycount 0.4.0, n-plus-one-sniffer and nplusone 1.0.0) were measured on **2026-11-10** in GitHub Actions. - Marks in the matrix: **(v)** verified by running the package or reading its installed source on that date (for queryspy, version 0.5.0; see above); **(r)** read in the package's PyPI description only, not run. Anything I could not check is marked as such. ## Who is who | Tool | Version (release date) | First release on PyPI | Targets | License | |---|---|---|---|---| | pytest-queryguard | 1.0.0 (2026-11-14) | 2026-10-10 | SQLAlchemy 2; Django (experimental until 1.1.0) | MIT | | [queryspy](https://github.com/sqla-native/queryspy) | 0.6.0 (2026-10-22) | 2026-08-04 | SQLAlchemy 2.0+, Python 3.11+ | MIT | | [pytest-querycount](https://github.com/ldavidsm/pytest-querycount) | 0.4.0 (2026-09-27) | 2026-09-27 | SQLAlchemy 2.x | MIT | | [nplusone](https://github.com/jmcarp/nplusone) | 1.0.0 (2018-05-21) | 2015-06-30 | Django, SQLAlchemy, Peewee | MIT | | [nplus1](https://github.com/huynguyengl99/nplus1) | 1.1.5 (2026-06-17) | 2026-05-22 | Django, SQLAlchemy, Flask-SQLAlchemy, Peewee, Celery; Python 3.11+ | MIT | | [django-zeal](https://github.com/taobojlen/django-zeal) | 2.3.0 (2026-10-14) | 2024-07-20 | Django | MIT | | [fastapi-nplusone](https://pypi.org/project/fastapi-nplusone/) | 0.1.0 (2026-02-10) | 2026-02-06 | FastAPI with SQLAlchemy | BSD-3-Clause | | [pytest-capquery](https://pypi.org/project/pytest-capquery/) | 0.3.3 (2026-04-04) | 2026-04-01 | SQLAlchemy, Python 3.13+ | CC BY-NC-SA 4.0 (see below) | | [django-nplus1](https://github.com/oliverhaas/django-nplus1) | 0.6.2 (2026-10-04) | 2026-04-05 | Django | MIT | | [django-query-doctor](https://github.com/hassanzaibhay/django-query-doctor) | 2.3.0 (2026-08-01) | 2026-03-14 | Django | MIT | | [n-plus-one-sniffer](https://github.com/async-workflows/n-plus-one-sniffer) | not on PyPI (repository created 2026-07-18) | not on PyPI | SQLAlchemy 2.0+ | MIT (repository) | | [orm-lens](https://github.com/FROWNINGdev/orm-lens) | 1.18.0 (2026-11-11) | 2026-07-12 as django-orm-lens, 2026-10-31 as orm-lens | Django; SQLAlchemy models in preview since 2026-10-31 | MIT | Release dates come from the PyPI JSON API on 2026-10-12, re-checked on 2026-10-13 and 2026-11-05; the rows of pytest-queryguard, django-nplus1, django-query-doctor and n-plus-one-sniffer were read on 2026-11-07 (PyPI and GitHub), the row of nplus1 on 2026-11-08. Every row was checked again on 2026-11-10 (PyPI, and GitHub for n-plus-one-sniffer, whose latest commit is still `d4790f8`): only pytest-queryguard had a new release. On 2026-11-14 (PyPI, and GitHub for n-plus-one-sniffer, still at `d4790f8`) only orm-lens (1.18.0, fixes to its Django model parser, its index suggestions and its factory generator) and pytest-queryguard (1.0.0) had. Most of these projects are young: pytest-queryguard, queryspy and pytest-querycount shipped their first release in the second half of 2026, so expect all of them to change. This table will be out of date; check the projects' own pages. orm-lens is a different kind of tool: it reads the source of Django and SQLAlchemy models and the code that queries them (static analysis of the syntax tree, with no database and without starting the application), and has a command line and an MCP server for AI coding agents. Its `nplusone` command looks for N+1 patterns in the code; it does not run tests or watch the statements a test sends, so it is not in the matrix below. Read from its PyPI description on 2026-11-05, and again on 2026-11-14 for 1.18.0 (its SQLAlchemy support is still marked preview), not run. pytest-queryguard has an experimental [static check](https://maciejziel.github.io/pytest-queryguard/static-check.html) of its own (since 0.8.0), which reads the mappers by importing your model modules and reports only lazy relationships read in a loop over a query inside one function, and an experimental [MCP server](https://maciejziel.github.io/pytest-queryguard/mcp.html), whose tools run the test suite and return the findings the tests produce. The two static checks were not compared. Five tools are not in the matrix below. nplus1 was read and run on 2026-11-08. For three others, found on 2026-11-07, what follows was read in their READMEs on that date, and for redline in its README and documentation on 2026-11-14; none of them was run: - **nplus1**: a rewrite of nplusone, published on PyPI as `nplus1` but installed under nplusone's import name, `nplusone` (v: the files of the 1.1.5 wheel), so a project can swap the package and keep its imports and `NPLUSONE_*` settings. Its README lists Python 3.11+, SQLAlchemy 2.0+, Django 4.2 to 5.2, Flask-SQLAlchemy, Peewee and Celery, call sites in its messages and a batch report mode (r). Its SQLAlchemy integration patches the same places as nplusone's, and behaves like it (v, Python 3.15, nplus1 1.1.5): on SQLAlchemy 2.0.54 a loop over `session.query(Order)` is reported, a loop over `session.scalars(select(Order))` is not; on SQLAlchemy 2.1.1 `import nplusone.ext.sqlalchemy` fails with `AttributeError: module 'sqlalchemy.orm.strategies' has no attribute 'LazyLoader'`. Its Django integration was not run. - **django-nplus1**: a Django-only fork of nplusone. Besides per-request detection, its README describes a "corpus mode" (`--nplus1-eager-corpus`) that reports an eager load only when no test of the whole pytest session read it, and a Celery integration that gives each task its own detection scope. pytest-queryguard's [unused-eager-load](https://maciejziel.github.io/pytest-queryguard/unused-eager-load.html) check is per test; its [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html#celery) measures each Celery task on its own. - **django-query-doctor**: Django; runs every query through analyzers for N+1, duplicate queries, missing indexes, "fat SELECT" (all columns loaded, few used), `len(qs)` instead of `count()` and `bool(qs)` instead of `exists()`, query complexity, and an analysis of the source of DRF `SerializerMethodField` methods. It works as middleware, a context manager, in tests and in CI. pytest-queryguard has no check for the `len()`/`count()` kind of misuse or for query complexity. - **n-plus-one-sniffer**: SQLAlchemy 2.0, installed from GitHub (not on PyPI). A context manager and a pytest plugin (a `no_n_plus_one` marker and an `n_plus_one` fixture) that flag a statement fingerprint repeated more than a threshold (3 by default) and suggest `selectinload`, `joinedload` or `subqueryload`. Its README does not mention relationship names, budgets or a baseline. - **redline**: a request profiler with a browser UI for Django, FastAPI, Flask and Litestar (packages `django-redline`, `fastapi-redline`, `flask-redline`, `litestar-redline` and `redline-core`, first on PyPI 2026-10-27, 0.5.0b1 on 2026-11-13, pre-release). It records requests to its own store and reports N+1 (the same read from the same line, 5 times by default) with a suggested fix, duplicate and slow queries, EXPLAIN, flamegraphs and load tests. Its pytest plugin checks the requests a test client sends: a `redline` marker (`max_queries`, `no_n_plus_one`, `max_external_calls`) or `--redline-all`, and `--redline-ratchet`, a file of per-test query counts that may only go down. Its documentation says the marker needs an instrumented in-process test client and checks each captured request; a test that sends no request fails the assertion. 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 | | pytest-queryguard | queryspy 0.6.0 | pytest-querycount 0.4.0 | nplusone 1.0.0 | django-zeal 2.3.0 | fastapi-nplusone 0.1.0 | pytest-capquery 0.3.3 | |---|---|---|---|---|---|---|---| | Works with SQLAlchemy 2 | yes | yes (v) | yes (v) | no: import fails on 2.1.4, silent or errors on 2.0.54 and 1.4.54 (v) | not applicable (Django only) (r) | SQLAlchemy, version not stated (r) | SQLAlchemy, version not stated (r) | | Fails tests with no marker or option | yes (v) | no: `--queryspy-strict` or `queryspy_fail_on`; budgets only with a marker or `queryspy_budget` (v) | no: markers, or `--querycount-max` (v) | not a pytest plugin (r) | needs a fixture or middleware setup (r) | logs a warning from a middleware (r) | needs a fixture; assertions in the test (r) | | N+1 from lazy-loaded relationships | yes (v) | yes (v) | by repeated statement shape, without the relationship name (v) | yes, SQLAlchemy 1.3.24 only (v) | yes, Django (r) | by repeated normalized query per request (r) | by an expected query count in a block (r) | | Repeated statements (`session.get()` loops, Core, `text()`) | yes (v) | `session.get()` loops yes; a Core `select()` loop and a loop with literal values not reported (v) | yes (v) | no (r) | Django only | yes (r) | by count (r) | | Deferred and expired column loads | yes, with the right hint (v) | yes, with the right hint (v) | as a repeated statement, generic hint (v) | no (r) | `.only()` and `.defer()` (r) | no (r) | no (r) | | Hint: `joinedload` or `selectinload` by cardinality | yes (v) | yes (v) | generic text (v) | no | Django hints (r) | no | no | | Query budget (`max_queries`) | yes (v) | yes (v) | yes (v) | no | no | no | exact count in a block (r) | | Budget failure lists every statement with its call site | yes (v) | no: the marker and `queryspy_budget` print only "expected at most N, got M"; the `assert_max_queries()` context manager adds the database time and N+1 findings, not the statements (v, 2026-10-13) | yes, with timing (v) | not applicable | not applicable | not applicable | prints a copy-paste assertion (r) | | Time budget and per-query timing | `max_db_time`, timing in `QueryLog` (v) | timing and the slowest statement; no time-budget option in the installed 0.5.0 (v, 2026-10-13) | timing in the failure and the report (v) | no | no | no | no | | Baseline for existing findings | yes (v) | yes (v) | no baseline; `--querycount-write-budgets` writes exact budgets into your tests (v) | no | allow-list in settings (r) | no | no | | SARIF and a GitHub Action | SARIF yes; a composite action in this repository, `action/` (v) | SARIF yes (v: `_serialize.py` in the installed package); an action, `sqla-native/queryspy@v0` (r) | not found: no SARIF code in the installed package (v) | no | no | no | no | | Missing-index check | PostgreSQL 16+, SQLite, and MySQL and MariaDB (tested in CI on MySQL 8.4 and MariaDB 11.8), with a `CREATE INDEX`; hypopg verification on PostgreSQL (v) | none: no EXPLAIN code in the installed package (v) | PostgreSQL only, `no_seq_scan`, with a `CREATE INDEX` suggestion (v) | no | no | no | no | | Unused eager loads | experimental, off by default (v) | no, deliberately (r) | no | yes, for Flask-SQLAlchemy and Django per its README (r) | no (r) | no | no | | Row-by-row write loops | opt-in (v) | not reported (v) | not reported (v) | no | no | no | no | | Per-finding ignore | marker, ini patterns, baseline and an `ignore()` block (v) | marker and an `ignore()` block (v) | `ignore=` for the index check only (r) | whitelist and an `ignore` block (r) | allow-list and an ignore block; since 2.3.0 an opt-in check for unused `zeal_ignore` blocks (r) | no | no | | In-app middleware and request panel | yes, since 0.5.0: ASGI and WSGI, optional panel (v) | yes: ASGI and WSGI, optional panel (v: modules present) | no | Django, Flask-SQLAlchemy, WSGI (r) | Django middleware (r) | yes, FastAPI middleware (r) | no | | Async SQLAlchemy | yes (v) | yes (v) | yes (v) | no | no | not stated | yes, through `sync_engine` (r) | | pytest-xdist | tested in CI | not stated | summary per worker; budgets and N+1 unaffected (r) | not stated | not stated | not stated | not stated | | Documentation site | this site | yes (r) | README | README | README | README | README | "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 has had an in-application mode (see [In-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html)) since 0.5.0; it is no longer experimental from 0.10.0. - **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 runs the whole suite on SQLite (also through aiosqlite) and on PostgreSQL 14 to 18 through pg8000 and asyncpg, once more with psycopg 3 (see the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html)); and on MySQL 8.4 and MariaDB 11.8 through PyMySQL and aiomysql. - **Django.** django-zeal and nplusone have covered Django for years; pytest-queryguard's Django support is new in 0.10.0 and left experimental in 1.1.0 (see [Django](https://maciejziel.github.io/pytest-queryguard/django.html)). - **Budgets in the test source.** `pytest-querycount --querycount-write-budgets` edits your tests to add an exact `max_queries` marker to each, so the budget is visible next to the test it limits. pytest-queryguard records the same counts in a separate [budget file](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file) (since 0.6.0) and never edits your code. - **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 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. ## Common problems with other tools The issue trackers of N+1 tools, in Python and in Ruby (Bullet and Prosopite, for Rails), show problems that users run into again and again. Some of them pytest-queryguard was built to avoid; the list below names only those, with where the behaviour is documented. The linked issues are evidence that the problem exists, not a judgement of the projects, several of which have fixed or worked around them since. - **Findings from test setup.** django-zeal fails tests in the setup phase when Factory Boy creates data ([django-zeal#19](https://github.com/taobojlen/django-zeal/issues/19)), and a Prosopite thread recommends wrapping only the part of a spec that is not setup ([prosopite#22](https://github.com/charkost/prosopite/issues/22)). pytest-queryguard measures only the test function body; fixtures are not measured (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html) and the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html#the-code-i-want-to-check-runs-in-a-fixture)). From 0.10.0 it also leaves out, by default, the N+1s of test code run in the body (a factory, a helper under `tests/`, the test's own loop) and counts them at the end of the run (see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)). - **No useful location.** nplusone's most requested feature is the call stack of a finding ([nplusone#22](https://github.com/jmcarp/nplusone/issues/22)); Bullet users ask for the same ([bullet#384](https://github.com/flyerhzm/bullet/issues/384)). pytest-queryguard reports the line of your code (`first at`), the callers (`called from`, `queryguard_stack_depth`) and, for a relationship, the line that loaded the parents; SQLAlchemy, pytest and installed packages are left out of the stack. - **Cannot gate on some kinds only.** Bullet users ask to turn single detectors off ([bullet#481](https://github.com/flyerhzm/bullet/issues/481)), and a queryspy user measured that every repeated-statement finding of a large suite was noise while the lazy-load findings were not ([queryspy#14](https://github.com/sqla-native/queryspy/issues/14)). `queryguard_fail_on` lets some kinds fail and others only warn (see the [configuration reference](https://maciejziel.github.io/pytest-queryguard/configuration.html)). - **Ignore lists that rot.** django-zeal users asked for a check that allow-list entries name fields that exist, since a typo fails silently ([django-zeal#25](https://github.com/taobojlen/django-zeal/issues/25)), and for ignore blocks that ignore nothing to be reported ([django-zeal#48](https://github.com/taobojlen/django-zeal/issues/48); 2.3.0 added an opt-in check). pytest-queryguard lists patterns, markers and `ignore()` blocks that matched nothing as "stale ignores", and an unknown kind in a pattern is a usage error (see [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html)). - **Schema queries reported as N+1.** Prosopite reported PostgreSQL catalog lookups made by `upsert_all` ([prosopite#26](https://github.com/charkost/prosopite/issues/26)). pytest-queryguard's repeat rules skip schema reflection: statements that start with `PRAGMA` or read `pg_catalog`, `information_schema` or SQLite's schema tables (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html); they still count for budgets). - **Overhead.** django-zeal once doubled the run time of a 5,000-test suite ([django-zeal#24](https://github.com/taobojlen/django-zeal/issues/24), fixed in 1.4.1). pytest-queryguard's overhead is measured and published, with the script, in [Performance](https://maciejziel.github.io/pytest-queryguard/performance.html). A problem that pytest-queryguard shares: a test that hands every request one `Session` makes the requests one unit of work, and queryspy#14 is also about that. See [A session per request in a test transaction](https://maciejziel.github.io/pytest-queryguard/recipes-test-transaction.html). ## What I measured ### Head-to-head in GitHub Actions Measured on **2026-11-10** by the [head-to-head workflow](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42846041338) (`.github/workflows/head-to-head.yml`, the adapters in `scripts/head_to_head/`), which anyone can run again from the Actions tab; it also runs once a month. Every tool that runs inside pytest and supports SQLAlchemy 2 is in it: queryspy 0.6.0, pytest-querycount 0.4.0, n-plus-one-sniffer (not on PyPI, installed from git at `d4790f8`, reported as 0.1.0) and nplusone 1.0.0. orm-lens is not: it reads source code and has no pytest mode. redline (found on 2026-11-14) is not either: its pytest marker checks requests sent through an instrumented test client, and all but six of the corpus scenarios send none. pytest-queryguard is 1.0.0rc1, run from its tag `v1.0.0rc1`; 1.0.0 has the same code. Python 3.13.18, SQLAlchemy 2.1.1, pytest 9.1.1 on `ubuntu-latest` (x86_64, 4 CPUs). How each tool is run, in its own job: its defaults plus what its own documentation says makes a test fail on an N+1. queryspy with `--queryspy-strict`; pytest-querycount and n-plus-one-sniffer with their `no_n_plus_one` marker on every test (n-plus-one-sniffer also needs an `nplusone_engine` fixture, which returns the `Engine` class so it sees every engine a scenario creates); nplusone with its documented generic use, `import nplusone.ext.sqlalchemy` and a `Profiler()` around each test. A scenario counts as flagged when the tool's own exception or message is in the failed test's report (or, for pytest-queryguard, when it recorded a finding); a test that failed for any other reason is an **error**, never a pass. A run with no tool at all passes every scenario. **Accuracy**, on the 278 scenarios of the [accuracy corpus](https://maciejziel.github.io/pytest-queryguard/accuracy.html) that ran (135 BUG, 143 CLEAN): | tool | BUG flagged | CLEAN flagged | errors | precision | recall (all BUG) | recall (BUG of kinds it claims) | |---|---|---|---|---|---|---| | pytest-queryguard, defaults | 117 | 2 | 0 | 98% | 87% | 97% | | pytest-queryguard, all opt-in rules | 134 | 9 | 0 | 94% | 99% | 99% | | queryspy 0.6.0 | 110 | 34 | 0 | 76% | 81% | 96% | | pytest-querycount 0.4.0 | 115 | 35 | 0 | 77% | 85% | 100% | | n-plus-one-sniffer `d4790f8` | 115 | 30 | 0 | 79% | 85% | 97% | | nplusone 1.0.0, SQLAlchemy 2.1.1 | 0 | 0 | 278 | n/a | 0% | 0% | | nplusone 1.0.0, SQLAlchemy 2.0.54 | 1 | 0 | 2 | 100% | 1% | 2% | Precision and recall per finding kind, with `n/a` for the kinds a tool does not claim (not 0%), and what each tool missed or flagged wrongly, are on the [accuracy page](https://maciejziel.github.io/pytest-queryguard/accuracy.html#comparison-with-other-tools) and in the run's summary. Read this table with its bias in mind: **the corpus was written by the author of pytest-queryguard, for pytest-queryguard.** Its CLEAN scenarios include the shapes pytest-queryguard was taught to leave alone (pagination, `IN` chunks, `selectinload` batches, `yield_per`), three of them use its own `ignore()` API, and the thresholds of the other tools were left at their defaults. What the table does show: the three working plugins catch nearly every N+1 shape they claim (pytest-querycount all of them), and each fails 30 to 35 of the 143 CLEAN scenarios, where pytest-queryguard fails 2 by default. nplusone does not import on SQLAlchemy 2.1, and on 2.0 it misses every lazy load of the corpus (2.0-style `select()` bypasses the `Query.__iter__` it patches) and raises `AttributeError` on two `subqueryload` scenarios. **Overhead**, same run (its `overhead` job ran twice: in the [first attempt](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42846041338/attempts/1) the run with no tool varied by 38% between rounds, so the numbers below are from [the second](https://github.com/MaciejZiel/pytest-queryguard/actions/runs/42846041338/attempts/2)), one job, every tool in its own virtual environment with the same Python, pytest and SQLAlchemy, the tools interleaved and their order reversed every round, 15 rounds, each a fresh process pinned to one core. Per statement: `scripts/compare/bench_micro.py` (in-memory SQLite), the best round. The suite: the generated 300-test suite of `scripts/bench_suite.py` against file SQLite, each tool set to look for N+1 in every test (pytest-querycount at `threshold=3`: its default of 2 fails the suite, which reads one parent twice per test). | | pytest-queryguard | queryspy | pytest-querycount | n-plus-one-sniffer | |---|---|---|---|---| | 300-test suite, added wall time (best of 15) | +14.8% | +25.8% | +16.3% | +23.0% | | 300-test suite, added wall time (median of 15) | +13.1% | +25.7% | +15.6% | +22.9% | | Core `select`, added per statement | +18.9 us | +8.4 us | +68.5 us | +14.0 us | | ORM `select`, added per statement | +33.5 us | +105.4 us | +107.6 us | +13.6 us | | Lazy load, added per statement | +66.0 us | +139.1 us | +121.3 us | +24.3 us | n-plus-one-sniffer adds the least to an ORM statement and a lazy load (one `before_cursor_execute` listener and a regular expression) but about 23% to the suite, so most of its cost is outside the statements measured here; queryspy adds the least to a Core statement. pytest-queryguard adds the least to the suite, with pytest-querycount close behind. The run of 2026-11-07 gave pytest-queryguard 0.8.0 +0.8% (best) and +1.7% (median) on the same suite. I could not reproduce it: the first attempt of this run gave +0.7% for the median too, but from a runner whose times varied by 38%, and on my laptop on 2026-11-10 (`scripts/bench_suite.py --runs 5`, CPU time of the test process) 0.8.0, 0.9.0, 0.10.0 and 1.0.0rc1 each added 18 to 20% to this suite. Read the suite cost as about a seventh to a fifth of the run time of a suite this cheap (about 5 ms a test), the same since 0.8.0, not 2%. nplusone has no overhead figure: it does not import on SQLAlchemy 2.1. Shared CI runners are noisy, which is why both the best and the median are given. ### N+1 and budgets on SQLite The head-to-head above runs the scenarios of the [accuracy page](https://maciejziel.github.io/pytest-queryguard/accuracy.html) under every tool (252 on the day it ran; the page now has 274, with precision and recall per finding kind). The smaller table below is the first comparison, of 2026-10-12. 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. | Scenario | Right verdict | queryguard | queryguard, small-repeat and write-loop on | queryspy | pytest-querycount | |---|---|---|---|---|---| | `01_lazy_n1_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `02a_selectinload_ok` | pass | pass | pass | pass | pass | | `02b_joinedload_ok` | pass | pass | pass | pass | pass | | `02c_subqueryload_ok` | pass | pass | pass | pass | pass | | `03_session_get_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `03b_session_get_loop_3_bad` | fail | pass (wrong) | FAIL | FAIL | FAIL | | `04_async_awaitable_attrs_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `04b_async_selectin_ok` | pass | pass | pass | pass | pass | | `04c_async_get_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `05a_repeat_x2` | - | pass | FAIL | FAIL | FAIL | | `05b_repeat_x3_batch_legit` | - | pass | FAIL | FAIL | FAIL | | `05c_repeat_x4` | - | pass | FAIL | FAIL | FAIL | | `05d_repeat_x5` | - | FAIL | FAIL | FAIL | FAIL | | `05e_repeat_x6` | - | FAIL | FAIL | FAIL | FAIL | | `06_legit_diff_shapes_ok` | pass | pass | pass | pass | pass | | `07a_budget_exact_ok` | pass | pass | pass | pass | pass | | `07b_budget_over_by_1_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `08_m2m_lazy_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `08b_m2m_selectin_ok` | pass | pass | pass | pass | pass | | `09_selfref_parent_walk_bad` | fail | pass (wrong) | pass (wrong) | pass (wrong) | pass (wrong) | | `09b_selfref_joined_ok` | pass | pass | pass | pass | pass | | `09c_selfref_kids_lazy_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `09d_many_to_one_lazy_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `09e_many_to_one_joinedload_ok` | pass | pass | pass | pass | pass | | `10a_dynamic_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `10b_writeonly_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `10c_raiseload_ok` | pass | pass | pass | pass | pass | | `11a_deferred_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `11b_undefer_ok` | pass | pass | pass | pass | pass | | `11c_expire_after_commit_refresh_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `11d_expire_after_commit_few_ok` | pass | pass | pass | FAIL (wrong) | FAIL (wrong) | | `11e_expire_on_commit_false_ok` | pass | pass | pass | pass | pass | | `12a_insert_flush_per_row` | - | pass | FAIL | pass | pass | | `12b_add_all_one_flush_ok` | pass | pass | pass | pass | pass | | `12c_core_insert_per_row` | - | pass | FAIL | pass | pass | | `12d_core_executemany_ok` | pass | pass | pass | pass | pass | | `12e_budget_counts_writes_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `13a_core_select_loop_bad` | fail | FAIL | FAIL | pass (wrong) | FAIL | | `13b_count_loop_bad` | fail | FAIL | FAIL | FAIL | FAIL | | `14a_pagination_3_pages_legit` | pass | pass | pass | FAIL (wrong) | FAIL (wrong) | | `14b_two_parents_legit` | pass | FAIL (wrong) | FAIL (wrong) | FAIL (wrong) | FAIL (wrong) | | `14c_same_parent_twice_ok` | pass | pass | pass | pass | pass | | `14d_identity_map_get_ok` | pass | pass | pass | pass | pass | | `14e_in_list_varying_len_legit` | pass | FAIL (wrong) | FAIL (wrong) | FAIL (wrong) | FAIL (wrong) | | `14f_literal_binds_loop_bad` | fail | FAIL | FAIL | pass (wrong) | FAIL | 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](https://maciejziel.github.io/pytest-queryguard/faq.html)). - 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. | Scenario | Right verdict | queryguard (pg8000) | queryguard (psycopg 3) | pytest-querycount (psycopg 3) | |---|---|---|---|---| | i01: equality on an unindexed FK column | fail | FAIL | FAIL | FAIL | | i02: equality on an indexed column | pass | pass | pass | pass | | i03: SELECT without a filter | pass | pass | pass | pass | | i04: primary-key lookup | pass | pass | pass | pass | | i05: lower(email) with an expression index | pass | pass | pass | pass | | i06: lower(city) with no expression index | fail | FAIL | FAIL | FAIL | | i07: filter on the second column of a two-column index | fail | FAIL | FAIL | pass (wrong) | | i08: filter on the first column of that index | pass | pass | pass | pass | | i09: LIKE prefix on an unindexed text column | fail | FAIL | FAIL | FAIL | | i10: ORDER BY id LIMIT 5, no filter | pass | pass | pass | pass | | i11: range on an unindexed timestamp | fail | FAIL | FAIL | FAIL | | i12: filter on a 2-row lookup table, no index | - | FAIL | FAIL | FAIL | | i13: join on an unindexed FK, no WHERE | pass | pass | pass | pass | | i14: IN list on an unindexed FK column | fail | FAIL | FAIL | FAIL | `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. ### Overhead See the [head-to-head](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions) above for the numbers of 2026-11-10 on a CI runner. The earlier measurement of 2026-11-05 on my machine (pytest-queryguard 0.5.0, pytest-querycount 0.4.0, queryspy 0.6.0), with its method and the script `scripts/compare/run.py`, is in [Performance](https://maciejziel.github.io/pytest-queryguard/performance.html#comparison-with-other-plugins): +1.8 to +2.4% for pytest-queryguard on the same suite, +27 to +29% for pytest-querycount and +40 to +43% for queryspy. ### 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, other SQLAlchemy versions, and any real application. Speed was measured on one machine, above; the overhead gate in `scripts/bench_overhead.py` covers 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: both pytest-queryguard (its [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html), since 0.5.0) and queryspy have ASGI and WSGI middleware and a request panel; the two were not compared on running apps. I did not test running queryspy together with pytest-queryguard. - You use queryspy in tests and want to move: see [Migrating from queryspy](https://maciejziel.github.io/pytest-queryguard/migrating-from-queryspy.html). - You want exact budgets written into your test files as markers: pytest-querycount (it and pytest-queryguard both register a `max_queries` marker; I did not test installing both). For budgets kept in a file next to the tests, pytest-queryguard's [budget file](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file). - You are on Django: django-zeal is the established choice; pytest-queryguard's [Django support](https://maciejziel.github.io/pytest-queryguard/django.html) is newer (0.10.0) and left experimental in 1.1.0. django-nplus1 and django-query-doctor were read, not run (see above). - You want to assert exact SQL: pytest-capquery, after checking its license. - You have nplusone on an old SQLAlchemy: see [Migrating from nplusone](https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html). If you only want nplusone to keep working, nplus1 (above) installs under the same import name; on SQLAlchemy it sees `session.query()` loops on 2.0 only. --- Source: https://maciejziel.github.io/pytest-queryguard/performance.html # Performance What pytest-queryguard costs when it is on, how that was measured, and what was done to lower it. The numbers come from one laptop and one afternoon; treat them as an order of magnitude and run the scripts on your own suite. ## What the plugin does per statement With measurement on, every statement passes through a few listeners: - `before_cursor_execute`: finds the call site (a walk up the stack to the first frame outside SQLAlchemy, pytest, the standard library and site-packages), tells lazy loads and column loads apart from ordinary queries by the ORM's options on the statement, builds one event and starts a timer. - `after_cursor_execute`: stops the timer. Once per test the collected statements are normalized and grouped by the detectors. The missing-index check, the index advisor and eager-load tracking are off by default and cost nothing until turned on; their costs are in the [FAQ](https://maciejziel.github.io/pytest-queryguard/faq.html#does-it-slow-my-tests-down). Part of the cost is not the plugin's own code. Registering any listener on these events makes SQLAlchemy take its slower event-dispatch path for every statement. In the benchmark below, four listeners that do nothing add about 6 microseconds per Core statement and about 8 per ORM statement, before any plugin code runs. That part cannot be removed without giving up the events. ## Method - Machine: Intel Core i5-13500H, 16 threads, Linux 7.0, Python 3.13.13, SQLAlchemy 2.1.1, pytest 9.1.1. Measurements were pinned to one core (`taskset`) and each configuration ran in a fresh process. - Micro-benchmark: `scripts/bench_overhead.py --statements 5000 --runs 15`. Core `select` by key and ORM `select` by primary key against in-memory SQLite, measurement off and on, the two interleaved, median of 15 runs. - Whole suite: `scripts/bench_suite.py --runs 7`. A generated suite of 300 tests; each test runs two Core statements, four ORM queries (one with `selectinload`, one lazy load), an insert with a commit, and a delete with a commit. It runs against a file-based SQLite database and against PostgreSQL 16.15 in a local Docker container (driver pg8000 1.31.5), once with `-p no:queryguard` and once with the plugin (default settings, mode `warn`). The time is taken inside pytest, from session start to session finish, so start-up and imports are not counted. - Before and after are the same scripts run against `main` as of 0.4.0rc2 (the "before" checkout) and against the branch with the changes below. Absolute times on this machine drifted by up to a factor of two between sessions (the same micro-benchmark gave 41 and 71 microseconds per Core statement with measurement off on different days), so only numbers measured back to back are compared below. ## Micro-benchmark: in-memory SQLite Added time per statement with measurement on, median of 15 runs, two rounds each (both rounds shown): | Statement | Measurement off | Before: added | After: added | |---|---|---|---| | Core `select` by key | 41 us | +10.5 us (+25 %), +11.3 us (+28 %) | +8.8 us (+21 %), +9.1 us (+22 %) | | ORM `select` by primary key | 76 us | +38.1 us (+50 %), +37.0 us (+48 %) | +30.0 us (+39 %), +31.9 us (+42 %) | The added cost fell by about 17 % in both loops. The percentages are large because an in-memory SQLite statement is almost free. In the same session a no-op listener floor of about +6 us (Core) and +8 us (ORM) is included in every "added" figure. Where the plugin's own part goes, per statement, measured by timing the listeners in place: about 4 us in the `before_cursor_execute` listener (call site, event, bookkeeping), 2 us in `do_orm_execute` and under 1 us in the timer listener. Those figures are from the 0.4.0 work. After 0.6.0 the plugin dropped its `do_orm_execute` listener: with any listener of that event SQLAlchemy prepares each ORM statement twice, which cost more than the listener itself. Strict mode and the unused eager-load check, both off by default, still add one, so a run with either pays that cost again. ## A realistic case: a suite of 300 tests | Backend | Wall clock, off | Wall clock, on | Added | |---|---|---|---| | File-based SQLite (local disk) | 38.0 to 39.0 ms/test | 37.9 to 39.6 ms/test | between -0.3 % and +2.2 % | | PostgreSQL 16 (local container) | 12.6 to 13.8 ms/test | 12.6 to 13.2 ms/test | between -9 % and 0 % | These are four independent runs of seven repetitions for each backend, two against the code before and two after the changes. The differences are smaller than the run-to-run noise: single runs on the same checkout differed by 10 % or more (fsync on a laptop disk, the database container), and the plugin often came out "faster" than the run without it. The honest reading is that on a suite that does real database work the overhead is below what this setup can resolve, in the order of a few percent at most. The CPU time of the test process (which leaves out waiting for the disk and the server) is less noisy and gives a rough upper figure: between -10 % and +7 % of the suite's CPU time, which is the same conclusion with a wider error bar. A profile of the same suite (`cProfile`, 300 tests) puts the time spent in the plugin's own functions at about 0.2 s in total, around 0.6 ms per test with the profiler's own inflation, and that figure fell by roughly 10 % with the changes below. Measured again on 2026-11-10 (`scripts/bench_suite.py --runs 5`, the same laptop, its scratch directory no longer waiting on the disk), the same suite ran at about 5.4 ms a test without the plugin, wall clock and CPU time alike, and 0.8.0, 0.9.0, 0.10.0 and 1.0.0rc1 each added 18 to 20 % of the CPU time (about 1 ms a test). The head-to-head of the same day on a GitHub runner gave 1.0.0rc1 +13 to +15 % (see [Comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions)). So the "few percent" above holds where each test waits for the disk or the server; on a suite whose tests cost a few milliseconds of CPU, expect a seventh to a fifth. Two limits of this measurement: the suite is small and made up for the benchmark, and the databases were on the same machine, so each statement was cheaper than it would be over a network. Over a network the plugin's share gets smaller, not larger. ## What changed - Call sites are shared: one immutable `CallSite` per source location instead of a new object for every statement, and the frame classification is read inline from its cache instead of through a function call per frame. - A statement is classified as a write once per execution, and without copying the statement text when it does not start with whitespace. - `normalize()` remembers its most recent 2048 results; a suite repeats the same statement texts, and the detectors normalized each one for every test. Behaviour is unchanged: the existing tests, the public API snapshot and the accuracy corpus give the same results, and each change has a regression test. ## The call path (0.10.0) Since 0.10.0 the `before_cursor_execute` listener walks the stack from the statement up to the test function (the hook call that ran it), not only to the first frame of the application: the call path of every statement tells a loop from calls on separate lines, and the files on it tell the test code from the application (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#calls-on-separate-lines)). The call site comes from the same walk. The walk from the first application frame to the test is the same for every pass of a loop, so its result is kept per measurement, looked up by the code object of each frame on that stretch and the instruction it is at: the passes after the first walk those frames without classifying them or computing their lines. The result depends on nothing else than the key and on answers kept per code object and per file for the whole session (is it a method of a `Session` subclass, is it test code), so the cache does not go stale; it is emptied when a measurement starts. Measured on the laptop above with Python 3.13.18, `scripts/bench_overhead.py --runs 9`, `main` (679e494) and the change interleaved, twice each: | Statement | Measurement off | before the walk (679e494): added | the walk, first version | 0.10.0: added | |---|---|---|---|---| | Core `select` by key | 40 to 42 us | +13.3 us, +13.5 us | +19.6 us, +19.6 us | +16.5 us, +15.7 us | | ORM `select` by primary key | 76 to 78 us | +27.9 us, +26.6 us | +43.2 us, +43.6 us | +33.6 us, +36.3 us | 1.0.0rc1 makes the walk cheaper again (SQLAlchemy's frames are passed with one lookup; see its changelog entry). On GitHub's runners, where the overhead gate measures, the ratio went down by 0.01 to 0.02 on some CPU models and stayed the same on others. On the laptop the difference is within the noise: measured on 2026-11-10 with Python 3.15.2, `scripts/bench_overhead.py --runs 9`, the tags `v0.10.0` and `v1.0.0rc1` interleaved. The laptop ran about 1.6 times slower after the first round (the "off" times); a round during which it changed speed is left out, and the two others are given separately: | Statement | Round | Measurement off | 0.10.0: added | 1.0.0rc1: added | |---|---|---|---|---| | Core `select` by key | 1 | 39 us | +16.2 us (41 %) | +16.0 us (41 %) | | Core `select` by key | 2 | 65 to 66 us | +26.6 us (40 %) | +26.4 us (40 %) | | ORM `select` by primary key | 1 | 75 to 76 us | +32.7 us (43 %) | +31.9 us (42 %) | | ORM `select` by primary key | 2 | 127 us | +54.3 us (43 %) | +54.5 us (43 %) | The first version classified every application frame and computed its line for every statement (about 0.5 microseconds a frame); the walk of a deep stack (a request through a web framework's test client) still costs more than this loop at the top level of a script. A cache keyed by `id()` replaced the one keyed by the code object for the methods of a `Session` subclass: a code object hashes its bytecode and constants, which made the first version of the walk twice as slow. ## What did not help - Registering the cursor listener with `retval=True` to skip SQLAlchemy's wrapper: no measurable change. - Disabling Python's garbage collector during the loop: no change, so the retained events are not what costs time. ## How the overhead grew before this The relative ORM overhead in the micro-benchmark rose from about 35 % to about 50 % between the overhead gate's first commit and 0.4.0rc2. There is no single commit behind it: each feature that looks at every statement added one to three microseconds (column-load detection, the ORM flush tag, the Session scope, the autoflush attribution), and an in-memory SQLite statement is so cheap that each step shows as a few percentage points. Run to run the same commit varies by about 5 points, so a bisect needs repeated, pinned runs. ## Comparison with other plugins A newer measurement, on a GitHub Actions runner with n-plus-one-sniffer too, is the [head-to-head](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions) of 2026-11-10. The one below is from my machine. pytest-queryguard 0.5.0, pytest-querycount 0.4.0 and queryspy 0.6.0, measured on 2026-11-05 with Python 3.14.4, SQLAlchemy 2.1.1 and pytest 9.1.1 on the machine above, by `scripts/compare/run.py`: - Whole suite: the generated 300-test suite of `scripts/bench_suite.py` against file-based SQLite, 9 rounds. Each tool ran with the settings that make it report N+1: pytest-queryguard with `--queryguard-mode=warn`, queryspy with `--queryspy-strict` (stack capture on, its default), pytest-querycount with a `no_n_plus_one(threshold=3)` marker on every test. - Per statement: a Core `select` by key, an ORM `select` by primary key and one lazy load, against in-memory SQLite (`scripts/compare/bench_micro.py`), 15 processes per tool, the fastest of 5 blocks of 2000 statements in each, then the median. Each tool has its own virtual environment with the same Python, pytest and SQLAlchemy; every run is a fresh process pinned to one core, the tools' runs are interleaved and their order reversed every round. Two complete runs, one after the other (the cells show both when they differ): | | pytest-queryguard | pytest-querycount | queryspy | |---|---|---|---| | 300-test suite, added time | +1.8 to +2.4 % | +27 to +29 % | +40 to +43 % | | Core `select`, added per statement | +25 to +27 us | +108 to +112 us | +13 us | | ORM `select`, added per statement | +55 to +66 us | +184 to +187 us | +172 to +176 us | | Lazy load, added per statement | +100 to +102 us | +189 us | +208 to +209 us | queryspy adds the least to a Core statement; on ORM statements, lazy loads and the whole suite pytest-queryguard adds the least. The absolute per-statement figures differ from the sections above because they are another session; as said in [Method](https://maciejziel.github.io/pytest-queryguard/performance.html#method), only numbers measured back to back compare. A first, informal measurement on 2026-11-01 used a development build of pytest-queryguard and earlier versions of the other two. ## Reproduce ```bash uv run python scripts/compare/run.py # the comparison above uv run python scripts/compare/run.py --queryguard . # this checkout instead of 0.5.0 uv run python scripts/bench_overhead.py --statements 5000 --runs 15 uv run python scripts/bench_suite.py --runs 7 uv run python scripts/bench_suite.py --runs 7 --backend postgres \ --url postgresql+pg8000://user:password@localhost:5432/bench ``` `bench_suite.py --src` measures another checkout, so two versions can be compared on the same machine; `scripts/bench_gate.py` is the CI check that guards the micro-benchmark ratio. --- Source: https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html # Migrating from nplusone [nplusone](https://github.com/jmcarp/nplusone) detects N+1 queries for Django, SQLAlchemy and Peewee. Its last release, 1.0.0, is from 2018-05-21. This page is for projects that used it with SQLAlchemy and now move to SQLAlchemy 2 and pytest-queryguard. If you use nplusone with Django, see [Django](https://maciejziel.github.io/pytest-queryguard/django.html): pytest-queryguard supports Django (no longer experimental since 1.1.0), and [Comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html) lists other tools that cover Django. ## If you only want nplusone to keep working [nplus1](https://pypi.org/project/nplus1/) is a rewrite of nplusone that installs under the same import name, `nplusone`. Replace `nplusone` with `nplus1` in your requirements only: the imports (`import nplusone...`), the `Profiler`, the `NPLUSONE_*` settings and the whitelist stay as they are. That is the smallest change, and for Django, Flask or Peewee it may be all you need. On SQLAlchemy it does not get you to 2.1 or to 2.0-style queries. I ran nplus1 1.1.5 on 2026-11-08 with the loop from [the table below](https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html#why-a-migration-is-needed): on SQLAlchemy 2.0.54 it reports the loop over `session.query(Order)` and nothing for `session.scalars(select(Order))`; on 2.1.1 `import nplusone.ext.sqlalchemy` fails with the same `AttributeError` as nplusone 1.0.0. What moving to pytest-queryguard adds, besides SQLAlchemy 2.0 and 2.1 with `select()`, async sessions and Core: - every test is checked with no fixture, and the failure names the application line, the test line that called it and the fix; - repeated statements (`session.get()` in a loop, Core and `text()`), column loads and, opt-in, write loops, not only lazy relationships; - query budgets (`max_queries`, a budget file) and a missing-index check; - a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) to adopt it on a suite with existing findings, and SARIF and JSON output for CI. ## Why a migration is needed nplusone patches `Query.__iter__` and SQLAlchemy's lazy loader. A 2.0-style query (`session.scalars(select(Order))`, `session.execute(select(...))`) does not go through `Query.__iter__`, so on SQLAlchemy 2.0 nplusone does not see the parents it loads and reports nothing; on 2.1 it does not import. I installed nplusone 1.0.0 next to several SQLAlchemy versions (Python 3.13 for the first three rows, Python 3.9 for the last) and ran the same N+1 loop: | SQLAlchemy | What happened | |---|---| | 2.1.4 | `import nplusone.ext.sqlalchemy` fails with `AttributeError: module 'sqlalchemy.orm.strategies' has no attribute 'LazyLoader'` | | 2.0.54 | Imports. A loop over `session.query(Order)` fails with `AttributeError: 'Query' object has no attribute '_offset'`. A loop over `session.scalars(select(Order))` runs and reports nothing | | 1.4.54 | The same two outcomes as 2.0.54 | | 1.3.24 | Works: `NPlusOneError: Potential n+1 query detected on Order.customer` | The [head-to-head run](https://maciejziel.github.io/pytest-queryguard/comparison.html#head-to-head-in-github-actions) of 2026-11-10 gives the same picture on a larger set: on the 278 scenarios of the [accuracy corpus](https://maciejziel.github.io/pytest-queryguard/accuracy.html), nplusone 1.0.0 did not import on SQLAlchemy 2.1.1, and on 2.0.54 it flagged 1 of the 135 scenarios with an N+1. So moving to SQLAlchemy 2 means moving off nplusone. The table is one small project on one date, not a full compatibility test of nplusone; the 2.0.54 and 2.1 rows were checked again on 2026-11-08 (2.1.1) with the project below. ## Find and replace What to change in the source, line by line. The [concept mapping](https://maciejziel.github.io/pytest-queryguard/migrating-from-nplusone.html#concept-mapping) below explains the differences. | Find | Replace with | |---|---| | `import nplusone.ext.sqlalchemy` | Delete it: the plugin registers itself with pytest | | `from nplusone.core import profiler` | Delete it | | An autouse fixture with `with profiler.Profiler():` | Delete the fixture: every test body is measured | | `profiler.Profiler(whitelist=[...])` in one test's fixture | `@pytest.mark.queryguard_ignore("Order.customer")` on the test | | `NPLUSONE_RAISE = True` | Nothing: `queryguard_mode = "fail"` is the default | | `NPLUSONE_RAISE = False` | `queryguard_mode = "warn"` | | `NPLUSONE_LOG`, `NPLUSONE_LOGGER`, `NPLUSONE_LOG_LEVEL`, `NPLUSONE_ERROR` | Nothing: a finding fails the test, or is a `QueryGuardWarning` in warn mode | | `NPLUSONE_WHITELIST = [{"label": "n_plus_one", "model": "Order", "field": "customer"}]` | `queryguard_ignore = ["relationship-load Order.customer"]` | | `{"label": "n_plus_one", "model": "Order"}` (every relationship of a model) | `"relationship-load Order.*"` in `queryguard_ignore` | | `{"label": "unused_eager_load", "model": "Order", "field": "customer"}` | `"unused-eager-load Order.customer"`; the check is experimental and off until `queryguard_unused_eager_load = "warn"` | | `with signals.ignore(signals.lazy_load):` | `with pytest_queryguard.ignore("relationship-load"):` | | `except NPlusOneError` or `pytest.raises(NPlusOneError)` around `Profiler()` | `with record_queries() as log:` and `log.assert_no_nplusone()`, which raises `pytest_queryguard.NPlusOneDetected` | | `NPlusOne(app)` (Flask) or `NPlusOneMiddleware` (WSGI) | `queryguard.watch(engine)` and `app.wsgi_app = queryguard.QueryGuardWSGI(app.wsgi_app)`, from `pytest_queryguard import app as queryguard` ([in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html)) | | `session.query(Order)` | Can stay: both `session.query()` and `select()` are measured | ## Concept mapping | nplusone | pytest-queryguard | |---|---| | `with profiler.Profiler():` around a test | Nothing: every test body is measured by default | | `Profiler()` raises `NPlusOneError` | A failing test: `queryguard: N+1 detected` (`queryguard_mode = fail`, the default) | | `NPLUSONE_RAISE = False` and logging | `queryguard_mode = warn`: a `QueryGuardWarning` and the test passes | | Label `n_plus_one` | Finding kind `relationship-load` (also `repeated-statement`, `column-load`, `write-loop`) | | Label `unused_eager_load` | Finding kind `unused-eager-load`, experimental, off by default: `queryguard_unused_eager_load = warn` | | `NPLUSONE_WHITELIST` | `queryguard_ignore` patterns: `kind label`, with optional `file=` and `function=` | | `signals.ignore(signals.lazy_load)` block | `with pytest_queryguard.ignore("relationship-load"):` ([the `ignore()` block](https://maciejziel.github.io/pytest-queryguard/ignoring.html#the-ignore-block)), a marker, `@pytest.mark.queryguard_ignore("Order.customer")` (or its alias `allow_nplusone`), or an ini pattern | | Whitelist patterns with `fnmatch` | The same: `fnmatch` patterns in markers and `queryguard_ignore` | | A profiler around one block | `record_queries()` and `log.assert_no_nplusone()` | | Flask, Django, WSGI middleware | Flask and any WSGI or ASGI app: the [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html) (`QueryGuardWSGI`, `QueryGuardASGI`). Django: as a test-suite check only ([Django](https://maciejziel.github.io/pytest-queryguard/django.html)); no in-application mode | ## Before and after The same project, the same test, in nplusone's world and in pytest-queryguard's. The loop is in `orders.py`, the application, and the test calls it. The "before" run is Python 3.9, SQLAlchemy 1.3.24, nplusone 1.0.0 and pytest 8.4.2. The "after" run is Python 3.15, SQLAlchemy 2.1.1 and pytest 9.1.1. Both were run on 2026-11-08. ### Before `conftest.py` turns nplusone on around every test (the `session` fixture, not shown, creates three customers with one order each and calls `session.expunge_all()`): ```python import pytest from nplusone.core import profiler import nplusone.ext.sqlalchemy # noqa: F401 (patches SQLAlchemy) @pytest.fixture(autouse=True) def nplusone_profiler(): with profiler.Profiler(): yield ``` ```python # orders.py from models import Order def customer_names(session): return [order.customer.name for order in session.query(Order)] ``` ```python # test_orders.py from orders import customer_names def test_customer_names(session): assert customer_names(session) == ["c1", "c2", "c3"] ``` ``` E nplusone.core.exceptions.NPlusOneError: Potential n+1 query detected on `Order.customer` =========================== short test summary info ============================ FAILED test_orders.py::test_customer_names - nplusone.core.exceptions.NPlusOn... 1 failed in 0.09s ``` ### After Delete the profiler fixture and the nplusone imports. Move the models to SQLAlchemy 2 (`DeclarativeBase`, `Mapped`) and, if you like, the query to `select()`; the test does not change: ```python # orders.py from sqlalchemy import select from sqlalchemy.orm import Session from models import Order def customer_names(session: Session) -> list[str]: return [order.customer.name for order in session.scalars(select(Order))] ``` ``` queryguard: N+1 detected Order.customer was lazy-loaded 3 times first at orders.py:8 in customer_names called from test_orders.py:5 in test_customer_names parents loaded at orders.py:8 in customer_names kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) =========================== short test summary info ============================ FAILED test_orders.py::test_customer_names - Failed: queryguard: N+1 detected 1 failed in 0.11s ``` The message names the line of the application, the line of the test that called it, and what to change. With `select(Order).options(joinedload(Order.customer))` the test passes. The same project with nplusone 1.0.0 on SQLAlchemy 2.0.54 passes: `1 passed`, nothing reported. ### Whitelist Before, in `conftest.py`: ```python with profiler.Profiler( whitelist=[{"label": "n_plus_one", "model": "Order", "field": "customer"}] ): yield ``` (the test passes: `1 passed`). After, either in the test: ```python @pytest.mark.queryguard_ignore("Order.customer") def test_customer_names(session): ... ``` or for the whole suite, in `pyproject.toml`: ```toml [tool.pytest.ini_options] queryguard_ignore = ["relationship-load Order.customer"] ``` Both give `1 passed`. ### Warn first nplusone logged by default and raised only with `NPLUSONE_RAISE`. To start with warnings: ```console $ pytest --queryguard-mode=warn test_orders.py::test_customer_names .../test_orders.py:4: QueryGuardWarning: queryguard: N+1 detected ... 1 passed, 1 warning in 0.08s ``` For a project that already has many findings, a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) lets you turn failing on for new findings only. ### A block instead of a profiler ```python from orders import customer_names from pytest_queryguard import record_queries def test_customer_names_in_a_block(session): with record_queries() as log: customer_names(session) log.assert_no_nplusone() ``` `assert_no_nplusone()` raises `NPlusOneDetected` with the same message. It does not read the ini options; see [Reading the queries](https://maciejziel.github.io/pytest-queryguard/python-api.html). ## Things that behave differently - nplusone's `Profiler` measures whatever runs inside its `with` block; with an autouse fixture that is the whole test including other fixtures' setup. pytest-queryguard measures only the test function body. - nplusone reports a loop wherever it is. pytest-queryguard by default leaves out the N+1s of test code: a loop written in the test function itself, in `conftest.py`, in a factory or in a helper under `tests/`. They are counted in a `queryguard: test code` section at the end of the run, and `pytest -o queryguard_test_code=warn` shows them. A test that only reads data in a loop of its own, as many nplusone examples do, passes; move the loop into the application, or see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code). - A lazy load of a many-to-one relationship for an object that is already in the session's identity map sends no SQL and is not a finding. In both tools the test data has to be loaded fresh (my examples call `session.expunge_all()` before the loop). - The default threshold is 2 different parents, and repeated statements need 5 runs; both can be changed. See [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html). - Only what I ran is covered here: nplusone's generic `Profiler` on SQLAlchemy 1.3.24, 2.0.54 and 2.1. I did not run its Flask, Django or Peewee integrations; the settings and the Flask and WSGI rows of the find-and-replace table were read in nplusone 1.0.0's installed source. --- Source: https://maciejziel.github.io/pytest-queryguard/migrating-from-queryspy.html # Migrating from queryspy [queryspy](https://github.com/sqla-native/queryspy) and pytest-queryguard both find N+1 queries and enforce query budgets for SQLAlchemy 2 in pytest. This page maps each queryspy setting to its pytest-queryguard equivalent. It was written against queryspy 0.5.0 (read in its installed package on 2026-10-13); on 2026-11-08 the options, markers and helpers below were checked again in the installed queryspy 0.6.0, the current release, and are the same (0.6.0 adds `--queryspy-report-format`). The pytest-queryguard column is current for 1.0.0. It is written by the author of pytest-queryguard; [Comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html) has the measured differences, including the ones where queryspy is ahead. Before you move: queryspy also runs in your application, as ASGI and WSGI middleware with a request panel. pytest-queryguard has had an [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html) of its own since 0.5.0, with ASGI and WSGI middleware and an optional panel; the two were not compared on running apps. If you keep the queryspy middleware, running both plugins in one pytest session was not tested (both read SQLAlchemy events, and both register a marker of their own, so the names do not clash). ## The main difference in defaults queryspy reports N+1 findings and fails no test on them unless you pass `--queryspy-strict` or set `queryspy_fail_on` (its budgets fail either way). pytest-queryguard fails a test on any finding with no configuration. To keep the queryspy behaviour while you migrate, start in warn mode and switch to `fail` once the suite is clean or baselined: ```toml [tool.pytest.ini_options] queryguard_mode = "warn" ``` ## Find and replace What to change in the source, line by line; the sections below explain each difference. | Find | Replace with | |---|---| | `--queryspy-strict` | Delete it: failing is the default | | `queryspy_fail_on = lazy_load, column_load` | `queryguard_fail_on = ["relationship-load", "column-load"]` | | `queryspy_budget = 20` | `queryguard_max_queries = 20` | | `--queryspy-report=queryspy.sarif` | `--queryguard-sarif=queryguard.sarif` | | `--queryspy-report=queryspy.json` | `--queryguard-json=queryguard.json` (another format) | | `--queryspy-baseline=PATH` | `--queryguard-baseline=PATH` (record it again: another format) | | `--queryspy-baseline-update` | `--queryguard-update-baseline` | | `@pytest.mark.queryspy(max_queries=3)` | `@pytest.mark.max_queries(3)` | | `@pytest.mark.queryspy(allow_n_plus_one=True)` | `@pytest.mark.queryguard_ignore` | | `from queryspy import assert_max_queries` | `from pytest_queryguard import max_queries` | | `with assert_max_queries(2):` | `with max_queries(2):` | | `from queryspy import no_n_plus_one` | `from pytest_queryguard import record_queries` | | `with no_n_plus_one():` | `with record_queries() as log:`, then `log.assert_no_nplusone()` after the block | | `from queryspy import record` | `from pytest_queryguard import record_queries` | | `with record() as recorder:` | `with record_queries() as log:` | | `with queryspy.ignore():` | `with pytest_queryguard.ignore("*"):` | | `queryspy.NPlusOneError` in `pytest.raises` | `pytest_queryguard.NPlusOneDetected` | | `queryspy.QueryCountError` in `pytest.raises` | `pytest_queryguard.QueryBudgetExceeded` | ## Loops in the test itself queryspy reports an N+1 wherever it runs in the test: a loop written in the test function fails it with `--queryspy-strict` (checked with queryspy 0.6.0 on 2026-11-08). pytest-queryguard, by default, leaves out the N+1s of test code: the test function, `conftest.py`, factories and helpers under `tests/`. They are counted in a `queryguard: test code` section at the end of the run, which names the tests. A loop in the application that a test calls is reported as usual. So after the move, a suite whose queryspy findings were in test code reports fewer findings; to see them, or to keep failing on them: ```toml [tool.pytest.ini_options] queryguard_test_code = "warn" # or "fail" ``` See [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code). ## Configuration | queryspy 0.6.0 | pytest-queryguard | |---|---| | `--queryspy-strict` | Nothing: the default `queryguard_mode = fail` fails on every finding kind | | `queryspy_fail_on = none` (the default: report only) | `queryguard_mode = warn` | | `queryspy_fail_on = n_plus_one` (every kind) | The default; `queryguard_fail_on` empty | | `queryspy_fail_on = lazy_load, column_load` | `queryguard_fail_on = ["relationship-load", "column-load"]`; the other kinds become warnings | | `queryspy_budget = 20` (every test) | `queryguard_max_queries = 20`: every test without a `max_queries` marker or a [budget file](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file) entry gets it ([Budgets](https://maciejziel.github.io/pytest-queryguard/budgets.html#a-default-budget-for-every-test)) | | `queryspy_capture_stacks = false` | No equivalent: the call site is always recorded | | `--queryspy-report=queryspy.sarif` (or `--queryspy-report-format=sarif`) | `--queryguard-sarif=queryguard.sarif` ([SARIF](https://maciejziel.github.io/pytest-queryguard/sarif.html)) | | `--queryspy-report=queryspy.json` (JSON) | `--queryguard-json=queryguard.json`: each test's statement count, database time and findings ([CI](https://maciejziel.github.io/pytest-queryguard/ci.html#query-counts-as-json)); the format differs | | `--queryspy-baseline=PATH` | `--queryguard-baseline=PATH`, or `queryguard_baseline` in the configuration | | `--queryspy-baseline-update` | `--queryguard-update-baseline` | | The queryspy GitHub Action | The [action in this repository](https://maciejziel.github.io/pytest-queryguard/ci.html) | ## Finding kinds and thresholds | queryspy | pytest-queryguard | Default threshold here | |---|---|---| | `lazy_load` | `relationship-load` | 2 parent objects (`queryguard_relationship_threshold`) | | `column_load` | `column-load` | 5 instances (`queryguard_column_load_threshold`) | | `repeated_statement` | `repeated-statement` | 5 runs (`queryguard_repeat_threshold`) | | not reported | `write-loop`, opt-in | off (`queryguard_write_loop_threshold`) | | not reported | `missing-index`, opt-in | off (`queryguard_index_check`) | queryspy uses one threshold of 2 for every kind. pytest-queryguard reports a repeated statement and column reloads from 5, so a loop of 2 to 4 statements that queryspy reported passes here. To get closer to queryspy, set `queryguard_small_repeat_threshold = 2`, which reports 2 to 4 runs from one source line with different parameters, or lower the thresholds themselves: ```toml [tool.pytest.ini_options] queryguard_small_repeat_threshold = 2 queryguard_column_load_threshold = 2 ``` ## Markers and helpers | queryspy | pytest-queryguard | |---|---| | `@pytest.mark.queryspy(max_queries=3)` | `@pytest.mark.max_queries(3)` | | `@pytest.mark.queryspy(allow_n_plus_one=True)` | `@pytest.mark.queryguard_ignore` (alias `allow_nplusone`), or with patterns to allow only some findings: `@pytest.mark.queryguard_ignore("Order.customer")` | | `@pytest.mark.queryspy(threshold=3)` | No per-test threshold marker: set the ini option, or use `record_queries()` with `assert_no_nplusone(relationship_threshold=3, repeat_threshold=3)` | | `@pytest.mark.queryspy(fail_on=...)` | No per-test equivalent; `queryguard_fail_on` applies to the suite | | `with assert_max_queries(2):` | `with max_queries(2):` (raises `QueryBudgetExceeded`, an `AssertionError`) | | `with assert_num_queries(2):` (exact) | `with queryguard.num_queries(2):` with the `queryguard` fixture (only the test's own thread counts), or `with record_queries() as log:` and then `assert len(log) == 2` | | `with no_n_plus_one():` | `with record_queries() as log:` and then `log.assert_no_nplusone()` | | `with record() as recorder:` | `with record_queries() as log:` ([Reading the queries](https://maciejziel.github.io/pytest-queryguard/python-api.html)) | | `with queryspy.ignore():` in application code | `with pytest_queryguard.ignore("*"):`, or name the kinds; threads started inside the block are not covered ([the `ignore()` block](https://maciejziel.github.io/pytest-queryguard/ignoring.html#the-ignore-block)) | | `QuerySpyMiddleware` (ASGI, WSGI), the panel | `QueryGuardASGI`, `QueryGuardWSGI` with `panel=True` ([in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html); not compared with queryspy's) | The helpers, side by side. They run against the fixed `fetch_customers`, the one in `app/customers_fixed.py` of [the first test](https://maciejziel.github.io/pytest-queryguard/getting-started.html#a-first-test), which loads the three customers with one `IN` query; the `app.customers` module of that page is the N+1 version, and both tests below fail against it: ```python from pytest_queryguard import max_queries, record_queries from app.customers_fixed import fetch_customers def test_fetch_customers_is_one_query(session): with record_queries() as log: fetch_customers(session, [1, 2, 3]) assert len(log) == 1 # queryspy: assert_num_queries(1) log.assert_no_nplusone(repeat_threshold=2) # queryspy: no_n_plus_one() def test_fetch_customers_budget(session): with max_queries(2): # queryspy: assert_max_queries(2) fetch_customers(session, [1, 2, 3]) ``` `assert_no_nplusone()` does not read the ini thresholds; pass them as arguments. Its defaults are 2 for relationships, 5 for repeats and 5 for column loads; the thresholds for small repeats and write loops are off unless passed (see [Reading the queries](https://maciejziel.github.io/pytest-queryguard/python-api.html)). ## A budget for every test `queryspy_budget` becomes `queryguard_max_queries`; a test with a `max_queries` marker, or with an entry in the budget file, keeps its own: ```toml [tool.pytest.ini_options] queryguard_max_queries = 20 ``` To record each test's current count instead of one number for all, use the [budget file](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file). ## The baseline The two baseline files have different formats, and an entry is not the same identity: pytest-queryguard keys on kind, label, file and function, with paths relative to pytest's rootdir. Record a new one with `pytest --queryguard-baseline=queryguard-baseline.json --queryguard-update-baseline` on a full run ([Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html)). Like queryspy, pytest-queryguard (since 1.1.0) leaves `AS` column aliases out of baseline labels, so one baseline works on SQLAlchemy 2.0 and 2.1; it also leaves out schema qualifiers, identifier quotes and the placeholder style, so the same file matches on SQLite and PostgreSQL ([Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html#what-an-entry-is)). ## Steps 1. `pip uninstall queryspy` (unless you keep its middleware), then `pip install pytest-queryguard`. 2. Translate the configuration with the tables above; start with `queryguard_mode = "warn"` if you ran queryspy without `--queryspy-strict`. 3. Replace `@pytest.mark.queryspy(...)` markers and the `queryspy` helpers. 4. Run the full suite, read the findings ([A test failed: now what](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html)), and record a baseline for those you keep. 5. Switch to `queryguard_mode = "fail"` (or remove the line) and update the CI job ([CI and GitHub Action](https://maciejziel.github.io/pytest-queryguard/ci.html)). --- Source: https://maciejziel.github.io/pytest-queryguard/limitations.html # Limitations - SQLAlchemy and the Django ORM ([Django](https://maciejziel.github.io/pytest-queryguard/django.html)). The plugin listens to SQLAlchemy's events and Django's execute wrapper, so a statement that goes through neither is not counted, not budgeted and not checked for indexes, and nothing says so. That covers a raw `sqlite3`, `psycopg` or `asyncpg` connection used directly, and Peewee, Tortoise ORM and any other ORM. SQLModel and Flask-SQLAlchemy build on SQLAlchemy sessions, so their statements should be seen (not tested here). If your suite passes but you expect findings, run with `--queryguard-report`: a test that shows 0 statements was not seen. - The repeat rules count per test by default, so a test that makes several independent requests in a loop, or through a server thread, can report a repeat that is no loop. A `Session` begun from lines of its own (a store method that opens a `Session` per call, called on separate lines) is counted on its own; `Session`s begun from the same lines add up. Calls on separate lines are told apart by their call path, also in one shared `Session` (see [Calls on separate lines](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#calls-on-separate-lines)), and a loop in the test that calls the application once per pass, where each call runs the statement once, is test code's repetition (see [Loops of the test](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#loops-of-the-test)). A loop in the test whose calls each run the statement twice or more is reported as the application's, also when the second run is no loop (a helper that looks one row up twice). The other way round, a loop of the application that the test's data gives one row per call (a customer with one order, in a loop of the test over customers) is taken for the test's repetition: give the test two rows, or set `queryguard_test_code = fail`. A generator or coroutine of the application that the test's loop resumes is one call, so loops of an `async` test that await the application keep counting together. To tell calls apart, the plugin keeps the frame of the last call into the application of each thread until the next statement or the end of the test, with that call's local variables; a test that checks an object of that call is garbage-collected right after it can see it alive. Set `queryguard_scope = session` to count per `Session`; that has limits of its own, listed in [Tests with several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html). - Test code is told from the application by file (see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)): test modules, `conftest.py`, files below a `tests` or `test` directory of the rootdir, and modules that define a factory_boy or polyfactory factory. Application code kept in such a file (a function written in the test module, a package named `test`) is taken for test code, and its N+1s are only counted in the summary at the end of the run by default; a helper of the tests kept elsewhere (a `testing.py` next to the application) is taken for the application. `queryguard_test_code = fail` reports both. Strict mode counts the lazy loads of all test lines together (it decides at the load), so a test that sends requests on separate lines can raise in strict mode and pass without it. - Each statement's call path is a walk of the stack up to the test function, which adds a few microseconds per statement (the stack depth decides how many; see [Performance](https://maciejziel.github.io/pytest-queryguard/performance.html)). - Everything in `site-packages` counts as library code. If your application is installed non-editable (for example `pip install .` in a Docker CI image), its frames are skipped too, and call sites point to the test file instead of the application line. - A call site is the first stack frame that is not SQLAlchemy, pytest, the standard library or `site-packages`. When a SQLAlchemy callable is handed to a worker thread directly, as in `await asyncio.to_thread(session.execute, stmt)`, `anyio.to_thread.run_sync(session.execute, stmt)` or `loop.run_in_executor(None, session.execute, stmt)`, the worker thread's stack holds only the executor, SQLAlchemy and the driver, so the finding says `first at `. In the SARIF file such a result is located at the test instead of being left out, but the line that issues the statement is not known. To get the call site, wrap the call in a function of your own, so that an application frame runs in the worker thread: `await asyncio.to_thread(lambda: session.execute(stmt))` or a named helper. - One measurement is active per process at a time, so tests in one process must run sequentially. Under pytest-xdist each worker measures its own tests, so detection and budgets work, and the workers send their counts and notes to the controller, which prints the report and the summary. - A thread a test starts and does not stop (a daemon worker, a server started in the test body) goes on into the tests after it: its statements count for whichever test is measured while they run, in its findings and its budgets, and cannot be told apart from that test's own. Stop and join such threads in the test or in the teardown of its fixture. Statements that run between two test bodies are not counted. - Tests that use `pytester` to run pytest in-process are also measured by the outer test, which sees the inner run's queries. Mark such tests with `queryguard_ignore` or use `pytester.runpytest_subprocess()`. - unittest `setUp` and `tearDown` run inside the test call, so their queries are counted, unlike pytest fixtures. - A non-strict `xfail` test that has an N+1 is reported as xfailed rather than XPASS, because the N+1 failure looks like the expected failure. - `INSERT`, `UPDATE` and `DELETE` never count towards the repeated-statement rule: at cursor level a unit-of-work flush cannot be told apart from an application write. Row-by-row writes from one source line can be reported by the opt-in `write-loop` kind (`queryguard_write_loop_threshold`), and a budget counts every statement, writes included. The statements of one ORM flush count as one write, so `add_all()` plus one `flush()` is not reported even when the dialect sends one `INSERT` per row. That relies on finding `Session._flush` on the call stack, a SQLAlchemy internal. - The repeat rules leave pagination and chunked `IN` loads alone only when the bound parameters show them (see "Pagination and chunks" in [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html)). Composite keyset conditions, keyset walks on a string or date column, MySQL's `LIMIT offset, count`, literal `IN` lists, `IN` lists shorter than 50 values and the same keys loaded twice in one test are still reported. A loop that sends 50 or more keys per item, each item's own and the same number for every item, looks like chunks and is not reported. Neither rule can tell a polling loop that repeats a statement on purpose from a loop-invariant query inside a loop: both repeat one statement with the same parameters, so both are reported. Raise `queryguard_repeat_threshold` or mark the test with `queryguard_ignore` for such code. The [accuracy page](https://maciejziel.github.io/pytest-queryguard/accuracy.html) lists the scenarios. - A few statements below the thresholds are not reported by default: fewer than five runs of one statement (`queryguard_small_repeat_threshold` reports them) and fewer than five instances that reload columns after a commit (`queryguard_column_load_threshold`). The same thresholds make the opt-in rules report legitimate code: a cached lookup that runs twice, or two objects read after a commit. - The write-loop rule cannot tell test seeding through the application (a repository's `create()` called per row by the test) or a per-row insert with its own error handling from a write loop in the code under test. Seeding through Factory Boy alone is test code and left out by default ([Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code)). The rule is off by default; see [Factory Boy and seeding](https://maciejziel.github.io/pytest-queryguard/recipes-factory-boy.html) for suites that seed in the test body. - The PostgreSQL index check needs PostgreSQL 16 or newer, and a sync engine or an async engine on asyncpg. It is tested on 16, 17 and 18; a newer server is checked, with one notice that it is untested (see [PostgreSQL versions](https://maciejziel.github.io/pytest-queryguard/index-check.html#postgresql-versions)). Other async drivers, such as psycopg's async mode, are skipped with a notice. The test suite uses pg8000 and asyncpg, and CI runs it once more with psycopg 3 (sync and async), installed only for that run since it is LGPL-licensed. psycopg2 is not run in CI; it was checked by hand during review and gives the same findings for plain statements, `%` in SQL, expanding `IN`, autocommit and `stream_results`. - On asyncpg the check needs PL/pgSQL, which PostgreSQL installs by default. Without it, each statement is counted as one PostgreSQL could not plan. After the first check, the connection knows the custom setting `queryguard.plan`, with an empty value: `current_setting('queryguard.plan')` returns `''` there instead of an error. - `EXPLAIN` does not run the statement, but PostgreSQL's planner evaluates calls to functions marked `IMMUTABLE` that have constant arguments while it plans. A function that is marked `IMMUTABLE` and still has a side effect therefore runs again for every plan the check asks for: once for the check's `EXPLAIN` and, when the [index advisor](https://maciejziel.github.io/pytest-queryguard/index-advisor.html) verifies its suggestions with hypopg, once more for the plan without them and twice for each hypothetical index it tries (three more for a single suggestion). The savepoint rolls back what is transactional, but not a `nextval()` call, an advisory lock or a write through `dblink` or `COPY ... TO PROGRAM`. A test that sees a sequence advance by more than it expects can look for such a function. - The index check looks only at `SELECT` and `WITH` statements and judges plans, not data: it says that no index can serve a filter, not that an existing index is a good one. A missing index that only a join would use (a join without a `WHERE` on that table) is not reported, because the plan for it depends on statistics. - The index check plans with a generic plan, which cannot see bound values. When a table has a partial index (`... WHERE status = 'open'`) whose predicate columns are all filtered by the statement, and one of them is compared with a parameter, the plan cannot tell whether the index serves that value. Such a statement is not reported and gets no advice; the session summary counts them (`N statements skipped: a partial index on may serve them; the generic plan cannot tell`). A genuinely missing index on such a statement is therefore not found. - A partitioned table is reported under its own name, once, and `queryguard_index_ignore_tables` matches that name, not the names of its partitions, also when the statement names a partition itself. An ignore or baseline entry that names a partition no longer matches (see the [index check](https://maciejziel.github.io/pytest-queryguard/index-check.html) for the migration). - The index check clears its catalog cache on DDL it sees through SQLAlchemy in the same process. DDL run another way while the session runs, through a raw DB-API connection, `psql`, another process or a function called from a `SELECT`, is not seen, and the check may judge an index by its old definition. A fresh pytest session starts with an empty cache. - On pytest 9.0 and 9.1, a wrongly typed value in the native `[tool.pytest]` table for one of pytest's own options (for example `console_output_style = 3`) stops pytest with an internal error, with or without this plugin. Wrong types for this plugin's options are reported as usage errors. - On SQLAlchemy 2.0.20 to 2.0.49 (and 2.1.0b1, 2.1.0b2), any `do_orm_execute` listener makes the outer statement's `yield_per`, `autoflush`, `populate_existing` and `identity_token` options load options of its `selectinload` and `immediateload` statements (SQLAlchemy issue 13301, fixed in 2.0.50). With `yield_per` the loader statement fails with "Can't use the ORM yield_per feature in conjunction with unique()"; with `autoflush=False` it no longer flushes. The plugin installs such a listener only for strict mode (`queryguard_strict`) and the unused eager-load check (`queryguard_unused_eager_load`), both off by default, and the in-app mode installs none; then, on those versions, it removes the inherited options from the loader statement before SQLAlchemy reads them, and the statement runs as it does without the plugin; the cursor still gets the outer statement's options. This happens only when the plugin's listeners are the only ones: with a `do_orm_execute` listener of your own the plugin changes nothing, because your listener triggers the same issue without the plugin. Upgrade to SQLAlchemy 2.0.50 or later to remove the cause. - Relationship and column loads are counted per `SELECT` sent to the database. A load that a `do_orm_execute` listener answers without one (a result cache) is not counted; one that runs several (horizontal sharding runs the lazy load once per shard, a `handle_error` listener that retries the statement) counts once per `SELECT`. - With several `Session`s on one connection (a second `Session` joined to the external connection of a "test in a transaction" fixture) and `queryguard_scope = session`, the query of a top-level `subqueryload` belongs to the `Session` that began on the connection last: SQLAlchemy does not say which `Session` runs it. Lazy loads, column loads and `selectinload` queries belong to their own `Session`. - SQLAlchemy checks an object's load context after the `refresh` instance event only while a listener for that event exists, and the plugin always has one (it notes which query read each object). A query with `populate_existing` and a `subqueryload()` of a self-referential relationship moves the objects to the subquery's context inside SQLAlchemy, before the event, so with the plugin installed SQLAlchemy emits `SAWarning: Loading context for <...> has changed within a load/refresh handler`; without it, the same load runs silently. The loaded data is the same. A suite with `filterwarnings = error` can ignore that message (`ignore:Loading context for:sqlalchemy.exc.SAWarning`) or use `selectinload()`, which does not move the objects. --- Source: https://maciejziel.github.io/pytest-queryguard/faq.html # FAQ The questions below are the ones to ask before adding a test-time check to a large suite: what it costs, how often it is wrong, how to silence it, and where it does not fit. The answers marked as measured link to how. ## How does this relate to SQLAlchemy's `raiseload`? `raiseload` is a loader option (`relationship(lazy="raise")`, or `.options(raiseload(Order.customer))` per query) that makes SQLAlchemy raise `InvalidRequestError` the moment code touches a relationship that was not loaded. It prevents lazy loading everywhere the option applies, in tests and in production, and it needs a change in the model or the query. pytest-queryguard changes nothing in your code. It watches the statements a test sends and reports patterns, including ones `raiseload` does not cover: the same statement repeated in a loop with `session.get()`, Core and `text()` statements, loops over deferred or expired columns, row-by-row writes and missing indexes. The two work together: `raiseload` blocks a lazy load, so a blocked access raises instead of reaching the database, and queryguard has no lazy load to count at that point. Use `raiseload` where you want a hard rule in the model, and queryguard where you want to find the places that need one. ## Two parents each lazy-load one relationship. Is that really a finding? When one query loaded both, yes. The relationship rule counts distinct parent objects per query line that loaded them, and the default threshold is 2, so `order.customer` read for two orders of one `select(Order)` is reported as `Order.customer was lazy-loaded 2 times`. That is the smallest N+1, and test databases hold a few rows, so a higher default would miss loops in tests that only create a couple of objects. Two orders loaded separately, at two different lines (`session.get(Order, 1)` and `session.get(Order, 2)`), each reading its customer, are not an N+1 and are not reported. When the plugin cannot tell which query loaded a parent (an object the test created, or one loaded before the test body), that parent counts with the parents of every query line, so two such objects, or one of them and one looked up, are reported. If two is too strict for your code, raise it: ```toml [tool.pytest.ini_options] queryguard_relationship_threshold = 3 ``` or silence one place, as in the next question. ## How often is it wrong? A finding means that a pattern happened in the test: the same relationship loaded for several parents, or the same `SELECT` run five times or more. It does not measure production latency. The patterns that are reported although the code is fine, all listed on the [Limitations](https://maciejziel.github.io/pytest-queryguard/limitations.html) page, are: - pagination or a batched `IN (...)` load that runs five or more pages or chunks; - a test that makes several independent requests, each repeating the same lookup (use `queryguard_scope = session`, see below); - two parent objects that each load a relationship once (the default threshold of 2, see the next question); - `IN (...)` queries with lists of different lengths: every length is one statement shape, so five such queries in one test are reported. What it misses: statements outside SQLAlchemy, statements in fixtures, and a self-referential walk up a parent chain. The [accuracy page](https://maciejziel.github.io/pytest-queryguard/accuracy.html) measures precision and recall per rule on a corpus of realistic scenarios, and the [comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html) runs the same scenarios through other tools. ## A finding is a false positive. How do I silence it? From the narrowest to the widest: - a few lines of code, in a test or in the application: `with pytest_queryguard.ignore("relationship-load"):`; - one finding, in one test: `@pytest.mark.queryguard_ignore("Order.customer", function="list_orders")`; - one finding, in the whole suite: a line in `queryguard_ignore`, for example `relationship-load Order.customer function=list_orders`; - a finding you cannot fix yet: put it in a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html); - a kind you do not want to fail tests: `queryguard_fail_on`, which makes the other kinds warnings; - a table that is fine to scan (index check): `queryguard_index_ignore_tables` or `@pytest.mark.allow_missing_index`. See [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html). Patterns that match nothing are listed as stale ignores, so they do not outlive the code. ## My integration test makes several requests and fails with repeated-statement By default the repeat rules count everything one test runs. A test that calls an API five times, with a test client for example, runs the same lookups (authentication, the organisation, a webhook) once per request, each in its own SQLAlchemy `Session`. Nothing loops, but the count is five. The failure says so when it can: `ran 9 times across 8 different Sessions or connection checkouts`, with a note naming the option. Set it to count each `Session` on its own: ```toml [tool.pytest.ini_options] queryguard_scope = "session" ``` A loop inside one request, or any code that runs the same statement five times in one `Session`, is still reported. The same applies to lazy loads, column loads and write loops. See [Tests with several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html) for how the scope is chosen and where it stops being exact. ## Can a tool get a callback for every finding? Not during the test run: pytest-queryguard has no pytest hook or callback that is called per finding. A tool that wants the findings (to send them to a dashboard, to count them over time, to annotate a pull request) reads the file that `--queryguard-json=PATH` writes at the end of the run. That file is the integration point for tooling: its format is versioned (`"format": 1`), the keys it promises are listed in [Stability](https://maciejziel.github.io/pytest-queryguard/stability.html), and they are described in [Query counts as JSON](https://maciejziel.github.io/pytest-queryguard/ci.html#query-counts-as-json). Each test lists its findings with `kind`, `label`, `count`, `file`, `line`, `function`, `stack` and `baselined`: ```python import json from pathlib import Path report = json.loads(Path("queryguard.json").read_text(encoding="utf-8")) if report["format"] != 1: raise SystemExit(f"unsupported queryguard JSON format {report['format']}") for test_id, test in report["tests"].items(): for finding in test["findings"]: if finding["baselined"]: continue print(test_id, finding["kind"], finding["label"], finding["count"], f"{finding['file']}:{finding['line']}") if not report["complete"]: print("the run stopped early; tests are missing") ``` Do not parse the terminal report or the `message` field: their wording is not stable. For code scanning, the [SARIF file](https://maciejziel.github.io/pytest-queryguard/sarif.html) is the other stable output. In a running application (not in tests), the [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html#settings) calls a `report` callable for every request with findings or over its budget, with a `RequestReport` that lists them. ## Does it work with pytest-xdist? Yes for detection, budgets, the baseline and SARIF: each worker measures its own tests, and the controller merges what the workers saw: the session report (`--queryguard-report`), the index check's summary and the stale-ignore list are the same as in a serial run, and so are the JSON, SARIF, baseline, budget and patch files. The test suite runs the plugin under `-n 2` to `-n 4`, with each `--dist` mode, in CI and compares the outputs with a serial run. ## Which PostgreSQL drivers work? N+1 detection and budgets hook SQLAlchemy events, not a driver, so they do not depend on the driver. The index check needs a driver it can talk to through SQLAlchemy: CI runs it with pg8000 (sync) and asyncpg (async), on PostgreSQL 14 to 18, and runs the whole suite once more with psycopg 3 as the sync driver, on PostgreSQL 17. psycopg 3 and psycopg2 are LGPL-licensed, so the package does not depend on them; psycopg 3 is installed only in that CI run, as a test dependency that is not shipped. psycopg2 is not run in CI; it was checked by hand during review and gave the same findings for plain statements, `%` in SQL, expanding `IN`, autocommit and `stream_results`. On 2026-10-12 the 14 index scenarios of the [comparison](https://maciejziel.github.io/pytest-queryguard/comparison.html) also gave the same results through psycopg 3 (3.3.6) as through pg8000, on PostgreSQL 17.11. Async drivers other than asyncpg (for example psycopg's async mode) are skipped by the index check, with a notice in the session summary; N+1 detection and budgets work on them, and CI runs psycopg's async mode too. ## Why was nothing reported for my test? - the loop is in the test itself, or in a helper, factory or `conftest.py` under `tests/`: that is test code, and its N+1s are left out by default. The run then ends with a `queryguard: test code` section that counts them and names the tests. Put the loop in a module of the application (the code you ship), or run `pytest -o queryguard_test_code=warn` to see them; see [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code); - the code under test ran in a fixture, not in the test body (see [the next question](https://maciejziel.github.io/pytest-queryguard/faq.html#the-code-i-want-to-check-runs-in-a-fixture)); - the statements did not come through SQLAlchemy (a raw `sqlite3` or other DB-API connection, Peewee, Tortoise ORM): the plugin does not see them, and `--queryguard-report` shows 0 statements for the test; - `queryguard_mode = off`, or the finding is in the baseline or an ignore pattern; - the count is below the threshold. `--queryguard-report` shows how many statements each test ran. ## The code I want to check runs in a fixture Only the test body is measured, on purpose: seeding data is meant to run many queries, and a session-scoped fixture would otherwise charge its setup to whichever test happens to run first. When the fixture is the code under test, wrap that code in [`record_queries()`](https://maciejziel.github.io/pytest-queryguard/python-api.html) and check the log: ```python import pytest from pytest_queryguard import record_queries @pytest.fixture def report_data(session): with record_queries() as log: data = build_report_data(session) # include the relationship reads log.assert_no_nplusone() return data ``` An N+1 in `build_report_data` then fails the setup of every test that uses the fixture, with the usual message: ```text E pytest_queryguard.NPlusOneDetected: queryguard: N+1 detected E Order.customer was lazy-loaded 3 times E first at test_recipe.py:40 in build_report_data ``` Two things to keep in mind: - only the block is recorded: a relationship the test reads later, after the fixture returned, is a lazy load outside it (and is measured with the test body instead); - the block records statements from every thread while it runs, so keep unrelated background work, such as a server thread started by another fixture, out of it. Thanks to @Muguett-DBY for [the recipe](https://github.com/pytest-dev/pytest/discussions/15166). ## Does it slow my tests down? It adds work per statement: a stack walk for the call site and a timer around the cursor call. `scripts/bench_overhead.py` measures it, and CI compares it with a stored baseline. Measured with `scripts/bench_overhead.py` on an Intel Core i5-13500H, Python 3.13, SQLAlchemy 2.1.1, median of 15 runs of 5000 statements pinned to one core, each configuration in a fresh process, against an **in-memory SQLite** database: | Per statement | Measurement off | On | Added | |---|---|---|---| | Core `select` by key | 41 us | 50 us | +9 us (+22 %) | | ORM `select` by primary key | 76 us | 107 us | +31 us (+40 %) | This table is from an earlier round of measurements. Since 0.10.0 the stack walk goes up to the test function, to tell a loop from calls on separate lines and test code from the application; measured on the same laptop, the added cost is then about 16 us per Core statement and 34 to 36 us per ORM statement (see [The call path](https://maciejziel.github.io/pytest-queryguard/performance.html#the-call-path-0100)). Two rounds differ by a few points, so read these as "about a fifth to two fifths" and not as exact figures. The percentages are large because an in-memory SQLite statement is almost free: the added cost is a fixed 9 to 31 microseconds, and a statement that goes to a real database takes far longer, so the share is much smaller there. These are micro-benchmarks. On a generated suite of 300 tests against a file-based SQLite database and against PostgreSQL the difference between running with and without the plugin was smaller than the run-to-run noise while each test waited for the disk; when they did not (about 5 ms of CPU a test), the plugin added 13 to 20 % to the run. See [Performance](https://maciejziel.github.io/pytest-queryguard/performance.html#a-realistic-case-a-suite-of-300-tests) for the method and numbers. The options that are off by default cost nothing until you turn them on: - The missing-index check (PostgreSQL) adds a few database round trips per distinct statement per test, about 1 ms per statement in the benchmark in [Missing-index check](https://maciejziel.github.io/pytest-queryguard/index-check.html). On SQLite it adds, over the "on" column above, +13.5 us for a repeated statement shape, +31.5 us for a repeated ORM statement and +34.5 us for a new shape that must be explained (`scripts/bench_overhead.py --index-check`). - Eager-load tracking (`queryguard_unused_eager_load`) wraps attribute reads: 171 ns per attribute read with the option off, 207 ns with it on but idle (outside a test body), 306 ns while a test body is tracked (`scripts/bench_eager_overhead.py`). - Unused-column tracking (`queryguard_unused_columns`) wraps the same reads and listens to each loaded row: about 170 ns per attribute read and 1.3 us per loaded row while a test body is tracked (`scripts/bench_columns_overhead.py`, see [Unused columns](https://maciejziel.github.io/pytest-queryguard/unused-columns.html)). The numbers depend on your machine and database. ## Does it work with Django, Peewee or raw SQL? Django's ORM, yes (no longer experimental since 1.1.0): see [Django](https://maciejziel.github.io/pytest-queryguard/django.html). Not with Peewee or Tortoise ORM. Raw SQL that goes through SQLAlchemy (`text()`, Core) is seen; a raw DB-API connection that SQLAlchemy does not manage is not. ## Can it break my test suite? It is designed not to. If one of its listeners raises, the plugin stops measuring for the rest of the session instead of failing your tests, issues a `QueryGuardInternalWarning` that names the listener, and prints a "queryguard: measurement stopped" section at the end of the session with the error and the line that raised it. A test then passes or fails on its own assertions. Invalid configuration values are the exception: they stop pytest at start-up with a usage error, before any test runs. On SQLAlchemy 2.0.20 to 2.0.49, every `do_orm_execute` listener makes the outer statement's `yield_per` and `autoflush` options reach its `selectinload` statement (SQLAlchemy issue 13301): `yield_per` then fails with "Can't use the ORM yield_per feature in conjunction with unique()". The plugin has such a listener only for strict mode and the unused eager-load check (both off by default) and undoes the effect for them, so a test does not fail only because the plugin is installed. A listener of your own triggers the issue with or without the plugin; upgrading to SQLAlchemy 2.0.50 or later fixes the cause. The checks do not change the SQL your code sends. The index check explains statements without running them: on PostgreSQL inside a savepoint that is rolled back, on SQLite and MySQL with `EXPLAIN`, so data and the test's transaction are left as they were. ## How do I turn it off? - For one run: `pytest -p no:queryguard` does not load the plugin at all (markers such as `max_queries` are then unknown, which pytest reports as a warning, or an error under `--strict-markers`); `pytest --queryguard-mode=off` loads it but stops N+1 detection, while budgets still apply. - For one test: `@pytest.mark.queryguard_ignore` without arguments. - For the suite: `queryguard_mode = "off"` in the configuration. ## Does it work in a monorepo? Yes. File paths in reports, the baseline and ignore patterns are relative to pytest's rootdir, so they depend on where pytest is configured, not on the directory you start it from. With one `pytest.ini` at the repository root and `pythonpath = services/a services/b`, a finding reads `first at services/a/app/orders.py:10` and the baseline stores that path. If each service has its own configuration file and its own rootdir, keep one baseline file per service: the same finding is `app/orders.py` there. Call sites skip everything in `site-packages`. Install the monorepo's own packages editable (`pip install -e`, `uv sync`), or a finding in a shared library points to the test instead of the library line. For GitHub code scanning from a service directory, the action's `working-directory` input keeps SARIF paths relative to the repository root (see [SARIF](https://maciejziel.github.io/pytest-queryguard/sarif.html)). ## Does it work with async tests? Yes. `AsyncSession` runs on a sync engine underneath, which the plugin watches, so an `async def` test run by pytest-asyncio or anyio is measured like any other, and the call site is the `await` in your code. Lazy loads through `awaitable_attrs` are reported as relationship loads. The [pytest-asyncio recipe](https://maciejziel.github.io/pytest-queryguard/recipes-pytest-asyncio.html) covers configuration mistakes that look like database problems (strict mode, async fixtures, event loop scopes), and [Getting started](https://maciejziel.github.io/pytest-queryguard/getting-started.html#async-and-fastapi) has an async FastAPI example. On SQLAlchemy 2.1 and newer install `sqlalchemy[asyncio]` for greenlet. ## Does it work on free-threaded Python? The free-threaded builds (CPython 3.13t and 3.14t, no GIL) are not in the package classifiers, so they are not a supported configuration. CI runs only the in-app mode's tests (`tests/inapp`) on 3.14t, not the whole suite. The whole suite was run once on CPython 3.14.4t with SQLAlchemy 2.1.1 and passed; 3.13t was not tried. On those builds the counters of a measurement (statements, loads and database time) are updated under a lock, so statements from several threads are all counted and budgets hold; on a build with the GIL no lock is taken. The stored events are list appends and the call-site caches are dictionaries, which CPython keeps consistent without the GIL; the sequence numbers that order Sessions and executions (`itertools.count`) stayed unique from 8 threads on 3.14.4t. The missing-index check and the unused-eager-load tracker check and then update shared sets, so with several threads they may do one step twice; those were not examined further. Every listener fails open, so a race there costs accuracy, not the test run. ## When should I not use it? - Your data access goes through neither SQLAlchemy 2 nor the Django ORM: Peewee, Tortoise ORM, raw DB-API connections. The plugin sees nothing there, and says nothing. - You want to see N+1 queries in production: the [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html) is for development and staging only. An APM tool fits production better. - Most of the database work in your suite happens in fixtures, or the tests that matter are end-to-end tests against a deployed service: only the test function body is measured, in the same process. - Every relationship already uses `lazy="raise"` and you only need that rule: `raiseload` gives a hard error with no plugin (see the first question). Repeated statements, budgets and the index check are still beyond it. - You need to assert the exact SQL a block sends: that is a snapshot tool's job; this plugin looks for patterns. --- Source: https://maciejziel.github.io/pytest-queryguard/configuration.html # Configuration reference | Option | Values | Default | Meaning | |---|---|---|---| | `queryguard_mode` | `fail`, `warn`, `off` | `fail` | `fail` fails a test with N+1. `warn` reports it as a `QueryGuardWarning` and lets the test pass. `off` turns detection off; tests without a budget are not measured. | | `queryguard_relationship_threshold` | integer ≥ 2 | `2` | Number of different parent objects, loaded by one query line, for which one relationship must be lazy-loaded to count as N+1 (see [relationship-load](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load)). | | `queryguard_repeat_threshold` | integer ≥ 2 | `5` | Number of times one normalized `SELECT` must run to count as N+1. Schema reflection (`PRAGMA`, `sqlite_master`, `pg_catalog`, `information_schema`) is not counted, see [how detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#repeated-statement). | | `queryguard_small_repeat_threshold` | `0` or integer ≥ 2, below the repeat threshold | `0` (off) | Number of runs of one statement from one source line, each with different parameters, that count as N+1 although they are below `queryguard_repeat_threshold`. Pagination and writes are not counted. | | `queryguard_scope` | `test`, `session` | `test` | Since 0.8.0 (before: `queryguard_repeat_scope`, see below). What the repeat, relationship, column-load and write-loop rules count together. `test` adds up everything one test runs, except calls on separate lines (see [Calls on separate lines](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#calls-on-separate-lines)). `session` counts each database session on its own: for SQLAlchemy, each `Session` (or, for a connection no `Session` opened, each connection checkout), which is what a test that makes several independent requests needs. See [Tests with several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html). | | `queryguard_write_loop_threshold` | `0` or integer ≥ 2 | `0` (off) | Number of single-row `INSERT`, `UPDATE` or `DELETE` statements of one shape from one source line that count as a write loop (kind `write-loop`). | | `queryguard_strict` | bool | `false` | Raise `NPlusOneDetected` at the lazy load that makes an N+1, with the test's traceback, instead of reporting it when the test ends. See [A test failed](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html#strict-mode-fail-at-the-access). | | `queryguard_show_patch` | bool | `false` | Since 0.8.0. Experimental (exempt from the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). Prints a patch under each `relationship-load` finding whose parent query line is certain: the loader option added to its `select()` or `query()` call, with the import. See [A patch for the parent query](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html#a-patch-for-the-parent-query). | | `queryguard_test_code` | `off`, `warn`, `fail` | `off` | Since 0.10.0. What the N+1 findings of the test code do: findings whose statements all ran in test modules, `conftest.py`, factories (factory_boy, polyfactory) or files below a `tests` or `test` directory, with no frame of the application on the stack (test tools such as factory_boy, model_bakery or Faker may lie between). `off` leaves them out and counts them in a section of the terminal summary that says how to see them, `warn` reports them as a `QueryGuardWarning`, `fail` reports them like the application's (as 0.9.0 and earlier did). See [Test code](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#test-code). | | `queryguard_cartesian_load` | `off`, `warn`, `fail` | `warn` | Reports a SELECT that joins two collections side by side, whose rows grow as their product (kind `cartesian-load`, see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#cartesian-load)); `warn` only warns, `fail` fails the test in `fail` mode. | | `queryguard_unused_eager_load` | `off`, `warn`, `fail` | `off` | Experimental (exempt from the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). Reports relationships a test eager-loads and never reads (kind `unused-eager-load`); `warn` only warns, `fail` fails the test in `fail` mode. See [docs/unused-eager-load.md](https://maciejziel.github.io/pytest-queryguard/unused-eager-load.html). | | `queryguard_unused_columns` | `off`, `warn`, `fail` | `off` | Experimental (exempt from the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). Reports a class whose rows a query loads with at least 8 columns when the test reads at most half of them, and suggests `load_only()` (kind `unused-columns`); `warn` only warns, `fail` fails the test in `fail` mode. See [docs/unused-columns.md](https://maciejziel.github.io/pytest-queryguard/unused-columns.html). | | `queryguard_fail_on` | kinds or `fnmatch` patterns, one per line | empty (no limit) | The finding kinds that fail a test in `fail` mode; the other kinds are reported as `QueryGuardWarning` and the test passes. For example `relationship-load` alone. Empty: every kind fails, except `cartesian-load`, `unused-eager-load` and `unused-columns`, which fail only when their own option is `fail` (by default `cartesian-load` warns and the other two are off). A kind fails when `queryguard_mode` is `fail`, its own option (if it has one) is `fail`, and `queryguard_fail_on` is empty or matches it. Budgets always fail. | | `queryguard_column_load_threshold` | integer ≥ 2 | `5` | Number of different instances of one class that must load deferred or expired columns on their own to count as N+1. | | `queryguard_max_events` | integer ≥ 0 | `10000` | Statements (and relationship loads) stored per test for reports. Beyond it they are only counted, and the report says so. `0` stores everything. | | `queryguard_stack_depth` | integer ≥ 0 | `3` | Lines of your code shown under `first at` as `called from`, innermost first: the callers that led to the finding, with SQLAlchemy, pytest and plugin frames left out. Also in the SARIF file (as a code flow) and the JSON file (`stack`). `0` shows none. Also how deep a `stack=` ignore pattern looks. | | `queryguard_ignore` | patterns, one per line | empty | Findings to leave out of reports: `KIND LABEL [file=GLOB] [function=GLOB] [stack=GLOB]`, see [Opting out](https://maciejziel.github.io/pytest-queryguard/ignoring.html); `stack` matches any frame of the reported stack, as deep as `queryguard_stack_depth`, see [Matching the call stack](https://maciejziel.github.io/pytest-queryguard/ignoring.html#matching-the-call-stack). | | `queryguard_baseline` | path | empty | Baseline file, relative to the rootdir: findings listed in it do not fail or warn, see [Baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html). | | `queryguard_budgets` | path | empty | Budget file, relative to the rootdir: each test listed in it fails above its number of queries, see [Budgets](https://maciejziel.github.io/pytest-queryguard/budgets.html#lock-todays-counts-the-budget-file). | | `queryguard_max_queries` | integer | empty | Default query budget of every test without a `max_queries` (or `queryguard_max_queries`) marker or an entry in the budget file. | | `queryguard_route_budgets` | `PATTERN=LIMIT`, one per line | empty | Since 1.1.0, experimental (exempt from the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). The most SQL statements one request of a route may run, for every request a test sends to a Starlette, FastAPI, Litestar, Flask or Django application: `GET /books/{id}=5`. The pattern is `METHOD path` or `path`, an `fnmatch` pattern matched against the route template and the request path; the first matching line wins. See [Budgets per route](https://maciejziel.github.io/pytest-queryguard/budgets.html#budgets-per-route-for-the-requests-of-a-test). | | `queryguard_route_default_budget` | integer ≥ 0 | empty | Since 1.1.0, experimental. The statement budget of every request that no `queryguard_route_budgets` pattern matches. | | `queryguard_index_check` | `true`, `false` | `false` | Checks each `SELECT` for a missing index (PostgreSQL 16 or newer, and `SELECT`, `UPDATE` and `DELETE` on SQLite, MySQL and MariaDB). | | `queryguard_index_advisor` | `true`, `false` | `true` | Suggests an index for each missing-index finding, see [Index advisor](https://maciejziel.github.io/pytest-queryguard/index-advisor.html). Used with the index check. | | `queryguard_hypopg` | `auto`, `on`, `off` | `auto` | Verifies the suggested indexes with the hypopg extension: `auto` when it is installed, `on` also creates it inside the check's savepoint, `off` never uses it. | | `queryguard_index_ignore_tables` | table names or `fnmatch` patterns, one per line | empty | Tables the index check ignores. A pattern matches `table` or `schema.table`, quoted or not, for example `countries`, `"UserAccount"`, `lookup_*` or `audit.*`; the spellings are the same as in the `queryguard_ignore` option and marker, see [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html). | Any invalid value stops pytest with a usage error. The options with a fixed set of values (`queryguard_mode`, `queryguard_scope`, `queryguard_test_code`, `queryguard_unused_eager_load`, `queryguard_unused_columns`, `queryguard_cartesian_load`, `queryguard_hypopg`) and `--queryguard-mode` ignore case and surrounding spaces: `WARN`, `Warn` and `warn` mean the same. In `pyproject.toml`: ```toml [tool.pytest.ini_options] queryguard_mode = "warn" queryguard_relationship_threshold = 3 queryguard_repeat_threshold = 10 queryguard_index_check = true queryguard_index_ignore_tables = ["countries", "lookup_*"] ``` With pytest 9 you can use the native TOML table instead: ```toml [tool.pytest] queryguard_mode = "warn" queryguard_relationship_threshold = 3 queryguard_repeat_threshold = 10 queryguard_index_check = true queryguard_index_ignore_tables = ["countries", "lookup_*"] ``` `pytest.ini` and `setup.cfg` work as usual. ### Deprecated names | Old name | Use instead | Since | Removed in | |---|---|---|---| | `queryguard_repeat_scope` (ini option) | `queryguard_scope` | 0.8.0 | 2.0 | | `repeat_scope=` of `QueryLog.assert_no_nplusone()` and `pytest_queryguard.app.Settings` | `scope=` | 0.8.0 | 2.0 | | `max_queries(n=...)` (marker keyword) | `max_queries(limit)` or `max_queries(limit=...)` | 0.8.0 | 2.0 | The old names keep working and emit a `QueryGuardDeprecationWarning` that names the replacement: an ini option once per run, a keyword at each place that uses it. Setting `queryguard_scope` and `queryguard_repeat_scope` (or `scope=` and `repeat_scope=`) to different values is an error. See the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#deprecation-policy). The warning classes, `pytest_queryguard.QueryGuardWarning` for N+1 and missing indexes in `warn` mode, `pytest_queryguard.QueryGuardInternalWarning` for an internal error and `pytest_queryguard.QueryGuardDeprecationWarning` for an option or name that a later release may remove (a `DeprecationWarning`, not a `QueryGuardWarning`), work with pytest's usual warning filters. For example, to turn the findings of `warn` mode back into failures for one job: ```toml [tool.pytest.ini_options] queryguard_mode = "warn" filterwarnings = ["error::pytest_queryguard.QueryGuardWarning"] ``` A blanket `filterwarnings = error` has the same effect: in `warn` mode it makes every finding fail its test, like `fail` mode. The failure shows the finding without the plugin's own source. An "error" filter never applies to `QueryGuardInternalWarning`: a bug in the plugin must not fail a test, so with `-W error` or `filterwarnings = error` that warning is still shown in the warnings summary, not raised. An "ignore" filter hides it as usual; the "queryguard: measurement stopped" section of the summary is printed either way. Command-line options: | Option | Meaning | |---|---| | `--queryguard-mode=fail\|warn\|off` | Overrides `queryguard_mode` for this run. | | `--queryguard-report` | Prints the 10 tests with the most queries at the end of the session (tests with equal counts by node id). | | `--queryguard-baseline=PATH` | Baseline file for this run; overrides `queryguard_baseline`. | | `--queryguard-sarif=PATH` | Writes the findings of this run to `PATH` as SARIF 2.1.0. | | `--queryguard-json=PATH` | Writes each test's statement counts (total and by verb), database time and findings to `PATH` as JSON, to compare runs. See [CI](https://maciejziel.github.io/pytest-queryguard/ci.html#query-counts-as-json). | | `--queryguard-update-baseline` | Writes the findings of this run to the baseline file instead of reporting them. | | `--queryguard-strict` | Turns `queryguard_strict` on for this run. | | `--no-queryguard-strict` | Turns strict mode off for this run, whatever `queryguard_strict` says. | | `--queryguard-show-patch` | Since 0.8.0, experimental. Turns `queryguard_show_patch` on for this run. | | `--no-queryguard-show-patch` | Turns `queryguard_show_patch` off for this run. | | `--queryguard-write-patch=PATH` | Since 0.8.0, experimental. Writes the patches of this run's findings to `PATH` as one file for `git apply`, from the rootdir; an empty file when there is none. See [A patch for the parent query](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html#a-patch-for-the-parent-query). | | `--queryguard-budgets=PATH` | Budget file for this run; overrides `queryguard_budgets`. | | `--queryguard-update-budgets` | Writes each test's query count of this run to the budget file. | | `--queryguard-index-check` | Turns the missing-index check on for this run. | | `--no-queryguard-index-check` | Turns the missing-index check off for this run, whatever `queryguard_index_check` says. | Of a flag and its `--no-` form, the last one on the command line wins. ## Markers | Marker | Meaning | |---|---| | `max_queries(limit)` | Fails the test if it runs more than `limit` SQL statements. See [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html). | | `max_db_time(seconds)` | Fails the test if its statements take more than that many seconds in total. | | `queryguard_max_queries(limit)`, `queryguard_max_db_time(seconds)` | Since 0.8.0. The same as `max_queries` and `max_db_time`, under names no other plugin reads; the closest marker counts, and when one place (function, class, module) has both spellings, the `queryguard_` one. Use them when [pytest-querycount](https://maciejziel.github.io/pytest-queryguard/budgets.html#pytest-querycount-and-the-max_queries-marker) is installed too. | | `queryguard_route_budgets(budgets, default=...)` | Since 1.1.0, experimental. Route budgets for the requests of this test, as a mapping `{"GET /books/{id}": 5}`, matched before the `queryguard_route_budgets` option's; `default=` replaces `queryguard_route_default_budget` (`None`: no default). See [Budgets per route](https://maciejziel.github.io/pytest-queryguard/budgets.html#budgets-per-route-for-the-requests-of-a-test). | | `queryguard_ignore(*labels, kind=..., file=..., function=..., stack=...)` | Since 0.8.0. Leaves out findings: all of them without arguments, or only those that match the `fnmatch` patterns, like the `queryguard_ignore` option. See [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html). | | `allow_nplusone(*labels, kind=..., file=..., function=..., stack=...)` | The name of `queryguard_ignore` before 0.8.0; a permanent alias, it does not warn. | | `allow_missing_index(*tables)` | Skips the missing-index check for the test, or only for the given tables. `queryguard_ignore` without arguments does not affect the index check; with patterns it also matches missing-index findings, as in `queryguard_ignore("public.audit_log", kind="missing-index")`. | ## Fixture | Fixture | Meaning | |---|---| | `queryguard` | `queryguard.max_queries(limit)` and `queryguard.num_queries(expected)` blocks that count the statements of the test's own thread or task, and `queryguard.queries`, the statements of the test function. See [Budgets and timing](https://maciejziel.github.io/pytest-queryguard/budgets.html#budgets-in-a-test-with-the-queryguard-fixture). | --- Source: https://maciejziel.github.io/pytest-queryguard/budgets.html # Budgets and timing Budgets fail a test that runs too many statements or spends too long in the database. They do not depend on N+1 detection and always fail, whatever `queryguard_mode` is set to. ## Query budgets with the `max_queries` marker ```python import pytest @pytest.mark.max_queries(3) def test_order_page(client): client.get("/orders/1") @pytest.mark.max_queries(limit=3) # the same, with a keyword def test_order_page_again(client): client.get("/orders/1") ``` The keyword is `limit`, as in the function below. Releases before 0.4 called it `n`; since 0.8.0 `n=3` still works but emits a `QueryGuardDeprecationWarning`, and it will be removed in 2.0 (see [Stability](https://maciejziel.github.io/pytest-queryguard/stability.html#deprecation-policy)). Write `max_queries(3)` or `max_queries(limit=3)` instead. `@pytest.mark.queryguard_max_queries(3)` (since 0.8.0) is the same marker under a name only this plugin reads. As with any marker, the closest one counts (the function's over the class's or the module's); when one place has both spellings, `queryguard_max_queries` counts. Use it when another plugin that reads `max_queries` is installed too, see [below](https://maciejziel.github.io/pytest-queryguard/budgets.html#pytest-querycount-and-the-max_queries-marker). The test fails when its body runs more SQL statements than the limit. The failure lists every statement with the line that issued it. Budgets count all statements, writes included, and they always fail, whatever `queryguard_mode` is set to. If the test already fails on its own, an exceeded budget is not reported, because the original failure wins. ## A default budget for every test ```ini [pytest] queryguard_max_queries = 20 ``` Every test without a `max_queries` marker (and without an entry in the budget file below) gets this budget. A test above it fails with the usual budget report and the line `(the limit is the queryguard_max_queries ini option, the default budget of tests without a marker)`. Empty, the default, means no default budget. ## Budgets per route, for the requests of a test Since 1.1.0, experimental (exempt from the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#experimental)). A test budget counts all a test runs; a route budget counts each request on its own. Give route patterns the most statements one request may run, and every test that sends a request to that route is held to it, whatever else the test does: ```toml [tool.pytest.ini_options] queryguard_route_budgets = [ "GET /books/{book_id}=5", "GET /api/*=10", ] queryguard_route_default_budget = 20 ``` In an ini file, one `PATTERN=LIMIT` per line: ```ini [pytest] queryguard_route_budgets = GET /books/{book_id}=5 GET /api/*=10 queryguard_route_default_budget = 20 ``` A pattern is `METHOD path` or `path`, the same as the [in-app mode's `budgets`](https://maciejziel.github.io/pytest-queryguard/in-app.html#fastapi-and-starlette): the path is an `fnmatch` pattern matched against the route template and the request path, and the first matching line wins. `queryguard_route_default_budget` is the budget of every request no pattern matches; without it, such a request has none. A request over its budget fails the test, once per route, with the statements and lines of the request that ran the most: ```text queryguard: route budget: GET /books/{book_id} may run at most 2 statements per request, GET /books/1 ran 3 (the limit is "GET /books/{book_id}" in queryguard_route_budgets) 1. SELECT books.id, books.title, books.author_id FROM books WHERE books.id = ? (app/main.py:31 in get_book) 2. SELECT authors.id, authors.name FROM authors WHERE authors.id = ? (app/main.py:32 in get_book) 3. SELECT count(*) AS count_1 FROM reviews WHERE reviews.book_id = ? (app/main.py:33 in get_book) ``` The statements of the test itself (its fixtures' data, a check after the request) do not count for any request. Route budgets fail the test whatever `queryguard_mode` is, as other budgets do, and are not judged in a test that fails on its own. The `queryguard_route_budgets` marker sets route budgets for one test (or a class or module). Its patterns are matched before those of the ini file, and `default=` replaces the default budget (`None` for none): ```python @pytest.mark.queryguard_route_budgets({"GET /books/*": 3}, default=None) def test_book_page(client): ... ``` What counts as a request, and its route: | Application | Request | Route template | |---|---|---| | Starlette, FastAPI | the call of the application, so a streamed body and background tasks count | the matched route's path (`/books/{book_id}`); for a mounted sub-application with the mount prefix (`/v1/books/{book_id}`) | | Litestar | the call of the application, streamed body and background tasks included | `path_template`, without parameter types (`/books/{book_id}` for `{book_id:int}`) | | Flask | from the call of the application until the body has been read to its end or closed; cleanup callbacks (`call_on_close`) included | the Flask rule (`/books/`) | | Django | `request_started` to `request_finished`, as the [Django support](https://maciejziel.github.io/pytest-queryguard/django.html) counts a request; `AsyncClient` requests too | `/` and `resolver_match.route` (`/books//`) | Any test client works, as each request is counted where the application handles it: Starlette's and FastAPI's `TestClient`, httpx's `ASGITransport`, Litestar's `TestClient`, Flask's `test_client()`, Django's `Client`. A request without a route template (a 404, a Django request no URL pattern resolved) matches by its path. The Flask test client reads a body only when the test does (`response.data`); a body never read counts up to the end of the test. Django ends a streamed response's request when its body is read to the end or closed; until then, statements of the test count for it. The plugin hooks into an application framework when a test with route budgets starts, so the framework must be imported by then: in the test module, a `conftest.py` or a fixture, as usual. A framework first imported inside the test function is measured from the next test on. A Django request that a middleware answers before URL resolution has no route or path: only `queryguard_route_default_budget` applies to it. Statements stored per request follow `queryguard_max_events`, as a test's do; past it they are counted but not listed. A Django request is counted from the statements its test stored, so in a test that ran more than `queryguard_max_events` statements its count stops there. ## Lock today's counts: the budget file A suite that already exists rarely has a sensible number per test. Record the numbers it has today, commit them, and every test that starts running more queries fails from then on: ```bash pytest --queryguard-budgets=queryguard-budgets.json --queryguard-update-budgets git add queryguard-budgets.json ``` ```ini [pytest] queryguard_budgets = queryguard-budgets.json ``` ```json { "format": 1, "budgets": { "tests/test_orders.py::test_list": 3, "tests/test_orders.py::test_detail": 2 } } ``` - A failure says where its limit comes from: `(the limit is the budget of this test in queryguard-budgets.json; if the new count is right, update it with --queryguard-update-budgets)`. - The order is: a `max_queries` marker, then the file, then `queryguard_max_queries`. - A test that runs fewer queries passes. Run the update again to lower its number (the summary says how many entries were added, removed, raised and lowered), so the file only tightens unless someone raises a number on purpose. - An update on part of the suite (`-k`, a path, `--lf`) keeps the entries of the tests that did not run; an update on the whole suite drops the entries of tests that no longer exist. A test that was skipped, failed, or errored in setup keeps its entry: a test that stopped halfway would otherwise get a number below what it runs when it passes. An update that stops early (`-x`, Ctrl-C, a collection error) does not write the file. It works the same with pytest-xdist. - A test with its own `max_queries` marker has no entry: the marker is the budget. - While the file is being updated neither its old numbers nor `queryguard_max_queries` are applied, so the update passes. - An update replaces a file it cannot read (a merge conflict) only when it covers the whole suite, and says so; a partial update leaves such a file alone. - The file has node ids, so a renamed or reparametrized test loses its entry until the next update. ## Query budgets with the `max_queries()` context manager ```python from pytest_queryguard import max_queries def test_checkout(service, cart): with max_queries(2): service.checkout(cart) ``` The block yields the same `QueryLog` as [`record_queries()`](https://maciejziel.github.io/pytest-queryguard/python-api.html), so the statements can be read after the block: ```python def test_checkout_statements(service, cart): with max_queries(2) as log: service.checkout(cart) assert log.count == 2 assert "INSERT" in log.queries[-1].sql ``` Only the statements inside the `with` block count. Above the limit it raises `QueryBudgetExceeded`, a subclass of `AssertionError`. The context manager does not depend on pytest, so it also works in a script or a benchmark. It checks the budget only; N+1 detection is done by the plugin around the whole test. ## Budgets in a test with the `queryguard` fixture ```python def test_checkout(queryguard, service, cart): with queryguard.max_queries(2): service.checkout(cart) def test_order_page(queryguard, client): with queryguard.num_queries(3) as log: # exactly 3 client.get("/orders/1") assert "JOIN" in log.queries[0].sql assert queryguard.count >= 3 # every statement of the test so far ``` Its blocks count only the statements of the test's own thread, or of its asyncio task, and of work run in a copy of their context: statements that a thread already running runs at the same time, such as a background worker or a server thread, do not count (a `TestClient` request does, see below). That makes them the equivalent of pytest-django's `django_assert_max_num_queries` and `django_assert_num_queries`: - `queryguard.max_queries(limit)` fails when the block runs more than `limit` statements. - `queryguard.num_queries(expected)` fails unless it runs exactly `expected`; fewer fail too. - Both raise `QueryBudgetExceeded` with every statement of the block and the line that issued it, and yield a `QueryLog` of the block (see [Reading the queries](https://maciejziel.github.io/pytest-queryguard/python-api.html)). Blocks can be nested, each counts its own statements, and an exception raised in the block wins over the budget. - The blocks count statements only. `log.assert_no_nplusone()` raises `RuntimeError` on their log; use `record_queries()` for that. A `Query.relationship` is filled in while the plugin measures the test, so not with `queryguard_mode = off`. - Tasks created inside a block, threads started with `asyncio.to_thread()` or `contextvars.copy_context().run()`, and, on a free-threaded build of Python 3.14, every thread started inside it, run in a copy of the block's context and count in it until the block ends. A task or thread that was running before the block does not count. `AsyncSession` and `create_async_engine` statements count in the task that awaits them. - `queryguard.queries` is a tuple of `Query` objects, the statements the test function has run so far, and `queryguard.count` their number. Unlike the blocks, they count every thread, as the plugin and `record_queries()` do, and so work with any async test runner (pytest-asyncio, anyio). Statements of fixtures, in their setup and teardown, are not in it, and reading them before the test function starts (in a fixture's setup) raises `RuntimeError`. A FastAPI or Starlette `TestClient`, such as the `client` above, runs each request in another thread but with a copy of the test's context, so the endpoint's statements count in the block, whether the client was opened in a fixture or in the test (checked by hand with anyio 3.7 and 4). A thread that was already running and does not copy the context, such as a live server or a worker pool, does not count: to count every thread in a block, use the `max_queries()` function or the marker above. Like them, the fixture fails whatever `queryguard_mode` is set to; with `queryguard_strict` an N+1 inside a block raises `NPlusOneDetected` at the access first, with the budget failure under it when the block had already gone over. After an internal error of the plugin, a block and the fixture warn with `QueryGuardInternalWarning` that their statements may be incomplete, and `num_queries()` no longer fails on too few statements. In type hints the fixture is `pytest_queryguard.QueryGuardFixture`. ## Time budgets with `max_db_time` ```python import pytest from pytest_queryguard import max_db_time @pytest.mark.max_db_time(0.25) # seconds def test_order_page(client): client.get("/orders/1") def test_checkout(service, cart): with max_db_time(0.1): service.checkout(cart) ``` The limit is the time the database and the driver took for the statements, measured around each cursor call, so slow Python code in the test does not count. The failure shows the total and the slowest statements with the line that issued them. A `max_queries` failure shows the total database time and its three slowest statements too. Like `max_queries`, the budget fails whatever `queryguard_mode` is set to. In `record_queries()`, each `Query` has a `duration` (seconds), and the log has `db_time` and `slowest(n)`. `@pytest.mark.queryguard_max_db_time(0.25)` (since 0.8.0) is the same marker under the plugin's own prefix, chosen the same way as `queryguard_max_queries`. ## pytest-querycount and the `max_queries` marker [pytest-querycount](https://github.com/ldavidsm/pytest-querycount) registers a `max_queries` marker of its own. With both plugins installed (checked with pytest-querycount 0.4.0), each reads every `max_queries` marker: - `@pytest.mark.max_queries(3)` is enforced twice, by each plugin with its own count. When pytest-querycount fails the test first, its failure is the one shown, since the original failure wins (see above). - `@pytest.mark.max_queries(limit=3)` stops the whole run at collection: pytest-querycount takes only a positional limit or `n=` and reports `@pytest.mark.max_queries needs a number`. - `pytest --querycount-write-budgets` writes `max_queries` markers into your test files, and pytest-queryguard then enforces them too. `max_db_time` and the other markers of pytest-queryguard do not clash. To keep the budgets of the two plugins apart, use the prefixed markers for pytest-queryguard, which pytest-querycount does not read: ```python @pytest.mark.queryguard_max_queries(3) # pytest-queryguard only @pytest.mark.max_queries(5) # pytest-querycount (and nothing else) def test_order_page(client): client.get("/orders/1") ``` With both markers on a test, pytest-queryguard uses `queryguard_max_queries` and ignores `max_queries`. While pytest-querycount is installed, `max_queries(n=3)`, its own spelling, does not emit the deprecation warning of `n=`. Or turn one plugin off for a run with `-p no:querycount` or `-p no:queryguard`. --- Source: https://maciejziel.github.io/pytest-queryguard/ignoring.html # Ignoring findings Four mechanisms leave findings out, from the narrowest to the widest: an [`ignore()` block](https://maciejziel.github.io/pytest-queryguard/ignoring.html#the-ignore-block) (a few lines of code), the `queryguard_ignore` marker (one test), the `queryguard_ignore` option (the whole suite) and a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) (everything that exists today). Budgets are never affected by them. ## The `queryguard_ignore` marker and option ```python @pytest.mark.queryguard_ignore def test_legacy_report(session): ... ``` The test is not checked for N+1. A `max_queries` marker on the same test is still enforced. The marker is new in 0.8.0. Its earlier name, `allow_nplusone`, takes the same arguments, means the same and stays as a permanent alias, without a warning; the "stale ignores" summary names the marker as the test spells it. To leave out one finding instead of the whole test, give the marker patterns (`fnmatch`, case-sensitive) for the finding's label, and optionally `kind`, `file`, `function` and [`stack`](https://maciejziel.github.io/pytest-queryguard/ignoring.html#matching-the-call-stack). A label written out exactly as the report prints it matches too, even when it holds `[` or `]`, which `fnmatch` would read as a character class: ```python @pytest.mark.queryguard_ignore("Order.customer", function="list_orders") def test_legacy_report(session): ... ``` The patterns match every kind of finding, `missing-index` included, so `@pytest.mark.queryguard_ignore("public.audit_log", kind="missing-index")` leaves out one table's finding. The bare marker leaves out N+1 findings only; `allow_missing_index` is the shortcut for skipping the index check for the test or for some tables. A table name is matched the same way in all four places that take one (the `queryguard_ignore(..., kind="missing-index")` marker, the `queryguard_ignore` option, `allow_missing_index` and `queryguard_index_ignore_tables`), so one spelling works everywhere. A pattern is a table name or `schema.table`, and each part is an identifier: - unquoted (`audit_log`, `UserAccount`, `audit_*`): compared as written (case-sensitive, `UserAccount` does not match `useraccount`), with `fnmatch` wildcards; - double-quoted (`"UserAccount"`, `public."UserAccount"`, `"my.table"`): compared exactly, with no wildcards, and may hold dots (`""` is a quote). A bare name matches the table in any schema; `public.audit_log` matches the table `audit_log` in the schema `public` also when the report prints it as `audit_log` because that schema is on the search path. The label as printed (`"UserAccount"`) matches too, and so does any `fnmatch` pattern on `table` or `schema.table` (`audit*` also matches every table in the schema `audit`). Schemas are known on PostgreSQL only; on SQLite and MySQL only bare names match. In the `queryguard_ignore` option and marker, this makes a bare name match the table in every schema: `missing-index audit_log` also leaves out the finding labelled `audit.audit_log`. The same patterns work for the whole suite in the `queryguard_ignore` option, one per line as `KIND LABEL [file=GLOB] [function=GLOB] [stack=GLOB]`: ```toml [tool.pytest.ini_options] queryguard_ignore = [ "relationship-load Order.customer", "repeated-statement SELECT * FROM settings*", "missing-index public.audit_log", ] ``` In `pytest.ini` (or `tox.ini`, `setup.cfg`), the option is a list of lines: write one pattern per indented line under it, without quotes: ```ini [pytest] queryguard_ignore = relationship-load Order.customer repeated-statement SELECT * FROM settings* missing-index public.audit_log ``` Every finding in the report has a line such as `kind: relationship-load label: Order.customer`; write the kind, a space and the label as the pattern. The kinds are `relationship-load` (the label is the relationship, as in `Order.customer`), `repeated-statement` (the normalized statement), `column-load` (the class and its deferred columns, as in `Book.summary`, or the class and the cause otherwise, as in `Book (expired)`, `Book (refresh)` or `Engineer (polymorphic)`), `write-loop` (the normalized `INSERT`, `UPDATE` or `DELETE`), `unused-eager-load` (the relationship, as in `Order.customer`), `unused-columns` (the class, as in `Account`), `cartesian-load` (the two collections, as in `Customer.notes + Customer.orders`) and `missing-index` (the table, with its schema as in the report; see below for the spellings a table name accepts). `file` is relative to pytest's rootdir, with forward slashes. Findings that no longer exist are easy to forget, so a pattern that matched nothing in the run is listed in the terminal summary under "stale ignores". Only a run of the whole suite that ran to the end lists the patterns: after `-k`, a file argument, `--lf`, `-x` or Ctrl-C, the test a pattern is for may not have run. ### Matching the call stack `file` and `function` match the line the finding is reported at, its `first at`. When that line is in a helper called from many places, `stack` leaves the finding out only when it comes through one of them. Here `names()` makes an N+1 that is accepted in the nightly admin export, and nowhere else: ```python # app/orders.py def names(session): return [order.customer.name for order in session.scalars(select(Order))] # app/admin/export.py from app import orders def export_orders(session): return write_csv(orders.names(session)) ``` ```toml [tool.pytest.ini_options] queryguard_ignore = [ "relationship-load Order.customer stack=app/admin/*", ] ``` or, for one test, `@pytest.mark.queryguard_ignore("Order.customer", stack="app/admin/export.py:export_orders")`. A test that calls `names()` from a view still fails (unless it went through the export first, see below). `stack` matches when any frame of the stack the report shows matches it: the `first at` line and each `called from` line under it. A pattern without a colon matches the frame's file (`app/admin/*`, `vendor/*`); one with a colon also matches `file:function` (`app/admin/export.py:export_orders`, `*:export_*`). The file is written as the report prints it, like for `file`: relative to the rootdir, with forward slashes. The kind, the label and any `file` and `function` must match too. The limits are those of the report: - Only `queryguard_stack_depth` callers are recorded (3 by default), and a caller further out is not matched. Raise the option when the frame you name is not among the `called from` lines; with `0`, `stack` matches the `first at` line only. A pattern that matches nothing is listed as stale. - The frames are the lines of your code: SQLAlchemy, pytest, the standard library and installed packages (any file under a `site-packages` or `dist-packages` directory) are never in the stack, so `stack` can exclude code vendored into the repository but cannot name an installed library. See [An N+1 inside an installed library](https://maciejziel.github.io/pytest-queryguard/ignoring.html#an-n1-inside-an-installed-library). - The stack is recorded the first time a line runs in a test. When one test reaches the helper from two places, the finding has the stack of the first, and only that one is matched: a test that runs the export and then the view has its N+1 left out, also the loads made through the view. The stack is not part of a finding's identity, so a [baseline](https://maciejziel.github.io/pytest-queryguard/baseline.html) entry still matches by kind, label, file and function. ### An N+1 inside an installed library A library can make the N+1 itself: a serializer, an admin or export package that reads a relationship of every object it is given. Its frames are never a call site, so the finding is reported at the first line of your own code on the way out, the line that called the library: ```python # app/export.py import tablib_export # installed in site-packages from sqlalchemy import select from app.models import Order def export_orders(session): orders = session.scalars(select(Order)).all() return tablib_export.to_csv(orders, columns=["id", "customer.name"]) ``` The report then starts with: ``` Order.customer was lazy-loaded 5 times first at app/export.py:10 in export_orders ``` What follows from that, checked by `tests/test_ignore.py`: - A pattern that names the library matches nothing: `file=*site-packages*`, `stack=*site-packages*` and `stack=*tablib_export*` never match, because no frame of the report is in the library. Such a pattern is listed under "stale ignores". - Name the line that calls it instead, with `file`, `function` or `stack`: ```toml [tool.pytest.ini_options] queryguard_ignore = [ "relationship-load Order.customer function=export_orders", ] ``` `stack=app/export.py:export_orders` works too, and also matches when the call to the library is further up, in a caller of the `first at` line (within `queryguard_stack_depth`). - Or wrap the call in an [`ignore()` block](https://maciejziel.github.io/pytest-queryguard/ignoring.html#the-ignore-block), which covers everything the library does inside it, whatever its findings are labelled: ```python from pytest_queryguard import ignore def export_orders(session): orders = session.scalars(select(Order)).all() with ignore("relationship-load", reason="tablib_export reads row by row"): return tablib_export.to_csv(orders, columns=["id", "customer.name"]) ``` There is no pattern for "anything that happens inside library X, wherever it is called from". The closest is a label pattern, which matches the relationship or statement wherever it runs, or one line per calling function. Better still, often, is to fix the input: load what the library reads with the query you hand it (`selectinload(Order.customer)`), and the library finds the relationship already loaded. A library installed in editable mode (`pip install -e`) or vendored into the repository is not under `site-packages`: its frames are call sites like your own, and `file`, `function` and `stack` match its lines. The methods of a `Session` subclass are the exception: the call site is the line that called the session (see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#what-is-measured)). ## The `ignore()` block To leave out what a few lines of code do, wherever they are called from, wrap them in `ignore()` with the kinds to leave out: ```python from pytest_queryguard import ignore def export_report(session): with ignore("relationship-load", reason="one-off export, runs at night"): for order in session.scalars(select(Order)): write_row(order, order.customer.name) ``` The block can be in a test or in the application code, where `pytest_queryguard` must then be importable; outside a measured test the block only sets a context variable. It also works as a decorator, on a function or a coroutine function: ```python @ignore("repeated-statement", "write-loop") def migrate_legacy_rows(session): ... ``` The kinds are the ones above, or `fnmatch` patterns for them (`"*"` for every kind); an unknown kind raises `ValueError`. `reason` is for the reader only. A finding is left out when every statement or load it counts ran inside a block for its kind. One of them outside the block is enough to report the finding in full, with every load counted, as if the block were not there. This catches the usual slip, a lazy load that happens after the block: ```python def test_export(session): with ignore("relationship-load"): orders = export_report(session) # lazy-loads order.customer assert orders[1].customer.name == "Ann" # one more lazy load, outside ``` Here the assertion lazy-loads one more customer outside the block, so the N+1 is reported with all its loads and the block is listed as stale. Put every access to the relationship inside the block (the assertion too), or load it with the query instead. In [strict mode](https://maciejziel.github.io/pytest-queryguard/when-a-test-fails.html#strict-mode-fail-at-the-access) a lazy load inside the block never raises; a later one outside it still can. The block applies to `record_queries()` and `log.assert_no_nplusone()` and to the [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html) too. Budgets (`max_queries`) still count the statements of the block. A pattern or marker that matches the same finding as a block is used too, and neither is listed as stale. When a test runs more statements or loads than `queryguard_max_events`, the plugin stops storing them and only counts the rest, so it cannot tell whether those ran inside the block: the blocks then leave nothing out in that test, and the findings are reported as without them. What "inside" means: the block is kept in a context variable, so it covers the thread or the asyncio task that entered it, and the tasks created inside it (a task starts with a copy of its creator's context), including `asyncio.to_thread()`. It does not cover: - a thread started inside the block (`threading.Thread`, a `ThreadPoolExecutor`, `loop.run_in_executor()`): a new thread starts with an empty context, unless it runs the work with `contextvars.copy_context().run(...)` or the interpreter makes threads inherit the context (`-X thread_inherit_context=1`, the default on the free-threaded build of Python 3.14); - a task or a thread that already existed, such as the server thread of a live-server test: the block of the test does not reach the requests it serves. A FastAPI or Starlette `TestClient` request is covered: it runs in a copy of the test's context. Put the block in the code that handles the request instead, or use the marker or `queryguard_ignore`. For the missing-index check, every run of the statement in the test counts, although it is explained only at its first run: a statement run inside the block and again outside it is reported, also when DDL in between made the check explain it again. A block that left out nothing in the whole run, in any test that entered it, is listed in the same "stale ignores" summary, with the file and line of the `with` (or of the decorator): ```text ignore() blocks that left out no finding in this run: app/reports.py:14: ignore('relationship-load') ``` A finding the block left out in `log.assert_no_nplusone()`, or in an in-app report made in the test, counts as well. Like the patterns, the blocks are listed only after a run of the whole suite that ran to the end, and also under pytest-xdist: the workers send the blocks they entered and used to the controller. A block is noted only when it is entered in the context of a measured test (its thread, its tasks, or a thread given a copy of its context), so a thread left over from another test does not count. It is not listed when it only ran in tests with a bare `queryguard_ignore` marker or past `queryguard_max_events`, or when none of its kinds was checked there (a `write-loop` block while `queryguard_write_loop_threshold` is off, a `missing-index` block without the index check). --- Source: https://maciejziel.github.io/pytest-queryguard/several-sessions.html # Tests with several sessions or requests The repeat rules count how often something happens. By default they count over the whole test, and a test that makes several independent requests then looks like a loop although nothing loops: ```python def test_five_requests(client, org): for _ in range(5): client.get(f"/orgs/{org.id}") # each request: its own Session, the # same authentication lookup ``` Every request opens its own `Session`, runs the same lookups, and closes it. The statement runs five times in the test and once in each request. ## Sessions begun on separate lines A store or service that opens a `Session` per call, called on separate lines of a test with no loop, runs its shared lookup once per call: ```python def test_set_tag(store): store.set_tag(1, "a", "x") # each call: its own Session, and the store.set_tag(2, "a", "y") # same lookup in a shared helper assert store.get_tags(1) == {"a": "x"} assert store.get_tags(2) == {"a": "y"} ``` The default scope counts these on their own, without any option. When a `Session` (or a connection checkout) begins, the plugin notes the application lines on the stack, from its first statement up to the test, as for a call site's callers. A `Session` begun from lines that no other `Session` of the test began from is counted alone. The `Session`s begun from the same lines (a loop, a comprehension, `asyncio.gather`, a thread pool, each depth of a recursion) are counted together, and so are all others whose lines repeat, whatever lines each began from: a loop whose passes call two store methods in turn is not split in two. A loop of three passes and three separate calls is a run of three, not of six. Requests that the application handles in another thread (Starlette's `TestClient` runs it in a portal thread) have no frame of the test on their stack: they begin from the same handler lines and are counted together as before. Sessions begun before the test (a fixture's) and those begun from lines first seen after 100,000 different ones in one test are counted together too. A pass of a loop whose `Session` begins from lines no other pass began from (a branch or a handler taken in one pass only) counts on its own, outside the loop: two passes through an `if` and its `else` look like two separate calls, and so does a call that primes a loop before it (`page = store.first()` and then `store.next(page)` in the loop), which then needs the threshold without it. As with `queryguard_scope = session`, a rule reports one finding per relationship or statement, from the unit with the most; another unit's N+1 of the same relationship is reported once that one is fixed. ## Requests on separate lines in one Session A test whose requests all use one `Session` (an application context pushed once for the suite, a scoped session that the requests share) has one scope, and the `Session`s cannot tell the requests apart: ```python def test_update_then_read(client): client.post("/vulns", json=VULN) # each request: the same workspace client.patch("/vulns/1", json=EDIT) # lookup and one lazy load, in the client.get("/vulns/1") # Session all requests share ``` The default scope tells them apart by the call path of each statement (see [Calls on separate lines](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#calls-on-separate-lines)): the requests sent from separate lines of the test are calls on separate lines, and each request's lookup and lazy load count on their own. Requests sent in a loop of the test have one call path, as an N+1 in the application has, and add up; a statement or load that each request runs once is then the test code's repetition (see [Loops of the test](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#loops-of-the-test)). Requests handled in another thread add up, as above. ## The option ```toml [tool.pytest.ini_options] queryguard_scope = "session" ``` | Value | What is counted together | |---|---| | `test` (default) | Everything the test runs, except `Session`s begun from lines of their own (see above); with Django, each request of the test client still counts on its own ([Django](https://maciejziel.github.io/pytest-queryguard/django.html#what-is-checked)). | | `session` | The statements, lazy loads, column loads and writes of one scope. A finding needs one scope to reach the threshold. | It applies to four kinds: `repeated-statement` (also the small-repeat rule), `relationship-load`, `column-load` and `write-loop`. `missing-index` and `unused-eager-load` do not count occurrences and are not affected. The default stays `test`, so an upgrade changes nothing until you set the option. Before 0.8.0 the option was called `queryguard_repeat_scope` (and the argument below `repeat_scope=`), although it scopes more than the repeat rule. The old names still work until 2.0 and emit a `QueryGuardDeprecationWarning`; setting both names to different values is a usage error. With `test`, a finding whose occurrences come from more than one scope says so: ``` the same statement ran 9 times across 8 different Sessions or connection checkouts first at app/auth.py:31 in current_user kind: repeated-statement label: SELECT users.id FROM users WHERE users.token = ? docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#repeated-statement note: if each belongs to a separate request or unit of work, this is not a loop; set queryguard_scope = session to count each Session on its own (QueryLog.assert_no_nplusone: scope='session') ``` With `session`, the message says `ran 6 times in one Session or connection checkout`, and the count is the largest one scope has. The identity of a finding (kind, label, file and function) and the baseline format do not change. `QueryLog.assert_no_nplusone(scope="session")` does the same for a recorded block; like the thresholds it does not read the ini option. ## How the scope is decided - A statement run through a `Session` (ORM queries, `session.execute(text())`, `session.connection()`) belongs to that `Session`: the plugin listens to `after_begin`, which hands it the `Session` and the connection it opened for the transaction. All transactions of one `Session` are one scope, so a loop with a `commit()` in every round is still a loop. - A statement on a connection no `Session` opened (`engine.connect()`, Core) is one scope per connection checkout. A checkout that runs `commit()` and goes on is still one scope. - Lazy loads and column loads belong to the `Session` that loaded them. - Async works the same: `AsyncSession` and `AsyncConnection` wrap a sync `Session` and `Connection`, and those are what the plugin sees. Concurrent tasks each have their own `AsyncSession`, so they are separate scopes. - A pooled or `StaticPool` connection that several checkouts share does not merge their scopes: every checkout gets a new `Connection` object, which is what the scope is attached to. A `Session` bound to one `Connection` that several `Session`s share (the "test transaction" pattern) is separated by `Session`, because each `Session` transaction tags the connection again. ## Limits - One `Session` is one scope. If a test passes the same `Session` to every request (a dependency override that returns the fixture's session), the requests are one scope and the repeats of requests sent in a loop add up again. Give each request its own `Session` in the override, or keep `test`. To keep the test's rolled-back transaction, bind each request's `Session` to the test's connection with `join_transaction_mode="create_savepoint"`; see [A session per request in a test transaction](https://maciejziel.github.io/pytest-queryguard/recipes-test-transaction.html). - Two `Session`s that use one shared `Connection` at the same time are not told apart; the later transaction's `Session` wins until the next one starts. - A loop that opens a new `Session` per round (`for x in xs: with Session() as s: s.get(...)`) is a real N+1 that `session` cannot see, because every round is its own scope. With `test` it is reported, with the note above. This is the cost of the option; check that a report with the note is really independent requests before you set it. - A statement the plugin cannot attach to a `Session` or `Connection` object (a connection type that refuses attributes) counts as one unknown scope. - The scope is attached to the Python objects, not to the database transaction, so it is unrelated to isolation levels or the pool. --- Source: https://maciejziel.github.io/pytest-queryguard/python-api.html # Reading the queries in a test `record_queries()` records the SQL statements a block sends and lets the test read them back: ```python from pytest_queryguard import record_queries from app.customers import fetch_customers from app.orders_fixed import list_orders def test_list_orders_loads_customers_with_the_orders(session): with record_queries() as log: list_orders(session) assert log.count == 1 assert "JOIN customer" in log.queries[0].sql assert all(query.relationship is None for query in log) def test_fetch_customers(session): with record_queries() as log: fetch_customers(session, [1, 2, 3]) log.assert_no_nplusone(repeat_threshold=2) ``` The two tests import from different modules of [the first test](https://maciejziel.github.io/pytest-queryguard/getting-started.html#a-first-test) project: `list_orders` from `app/orders_fixed.py`, which loads the customers with the orders, and `fetch_customers` from `app/customers.py`, the version with the loop, which is the one that fails the second test. Against the N+1 `app.orders` the first test fails on `log.count == 1`. `log.queries` is a tuple of `Query` objects, in the order the statements ran. The log is also sized, iterable and indexable (`len(log)`, `for query in log`, `log[i]` and `log[a:b]`) but not a `collections.abc.Sequence`, because `log.count` is a number and not the `count(value)` method of a sequence. An empty log is falsy. Each `Query` has: - `sql`: the statement as the ORM sent it to the database driver (with SQLAlchemy: the text SQLAlchemy passed to the DBAPI cursor); - `callsite`: a `CallSite` with `filename`, `lineno` and `function`, the first frame outside SQLAlchemy, pytest, the standard library, `site-packages`, the plugin and the methods of a `Session` subclass, or `None`. Its `callers` are the `CallSite`s of the application lines that called it, innermost first, up to the test (`queryguard_stack_depth` of them, 3 by default), as seen the first time that line ran in the block or test; they are not part of the equality of two `CallSite`s; - `relationship`: the model relationship the statement loaded, as `Class.attribute` such as `"Order.customer"` (with SQLAlchemy: loaded lazily, or as the extra query of an eager loader such as `selectinload`), or `None`; - `duration`: seconds spent in the database and driver, measured around the cursor call, or `None` if the statement is still running or raised an error. `log.count` is the number of statements. Both grow inside the block and stay fixed after it. Statements from other threads are recorded too. `log.db_time` is the total recorded database time. It grows as statements finish inside the block and stays fixed after it, like the query details. A statement still running when the block ends keeps `duration=None` in that log; finishing later does not change the log's total. Join worker threads inside the block to include their completed timings. `QueryLog` is not constructible by users: `record_queries()` is the only way to get one, and its constructor may change in any release. Use the class for type hints only. `log.assert_no_nplusone()` applies the plugin's N+1 rules to the block: relationship loads, repeated statements and column loads, plus small repeats and write loops when asked for. It raises `NPlusOneDetected`, a subclass of `AssertionError`, with the plugin's message, with paths relative to pytest's rootdir (outside pytest, to the working directory). The thresholds are keyword-only arguments, with the same defaults as the ini options: | Argument | Default | Ini option | Rule | |---|---|---|---| | `relationship_threshold` | `2` | `queryguard_relationship_threshold` | One relationship lazy-loaded for this many different parent objects that one query line loaded. | | `repeat_threshold` | `5` | `queryguard_repeat_threshold` | One `SELECT` that ran this many times. | | `column_load_threshold` | `5` | `queryguard_column_load_threshold` | This many instances of one class each loading deferred or expired columns on their own (kind `column-load`). | | `small_repeat_threshold` | `None` (off) | `queryguard_small_repeat_threshold` | An integer of at least 2 and below `repeat_threshold`: a statement that ran this many times from one line, each time with other parameters, counts too. | | `write_loop_threshold` | `None` (off) | `queryguard_write_loop_threshold` | An integer of at least 2: this many single-row `INSERT`, `UPDATE` or `DELETE` statements of one shape from one line (kind `write-loop`). | | `scope` | `"test"` | `queryguard_scope` | See below. `repeat_scope=`, its name before 0.8.0, still works with a `QueryGuardDeprecationWarning` until 2.0. | An ini option set to `0` for "off" is `None` here. `scope="session"` counts each database session on its own (for SQLAlchemy, each `Session` or connection checkout), like `queryguard_scope = session` (see [Tests with several sessions or requests](https://maciejziel.github.io/pytest-queryguard/several-sessions.html)); the default is `"test"`. It does not read the ini options, `queryguard_mode` or the `queryguard_ignore` marker; calling it is an explicit request. It does leave out what ran inside an [`ignore()` block](https://maciejziel.github.io/pytest-queryguard/python-api.html#leaving-out-a-block-ignore), as the plugin does. A project that sets `queryguard_repeat_threshold = 10` in its configuration therefore has to pass `repeat_threshold=10` here as well, or the helper keeps using 5 (the same for `queryguard_relationship_threshold` and `relationship_threshold`). With the `fetch_customers` loop from [the first test](https://maciejziel.github.io/pytest-queryguard/getting-started.html#a-first-test), the plugin accepts 3 lookups, because its threshold is 5, while the stricter call above does not (`pytest --tb=short`, Python 3.13, SQLAlchemy 2.1): ``` tests/test_queries.py .F [100%] =================================== FAILURES =================================== _____________________________ test_fetch_customers _____________________________ tests/test_queries.py:18: in test_fetch_customers log.assert_no_nplusone(repeat_threshold=2) E pytest_queryguard.NPlusOneDetected: queryguard: N+1 detected E E the same statement ran 3 times E first at app/customers.py:9 in fetch_customers E kind: repeated-statement label: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? E fix: fetch all rows in one query (WHERE id IN (...)) instead of in a loop =========================== short test summary info ============================ FAILED tests/test_queries.py::test_fetch_customers - pytest_queryguard.NPlusO... ========================= 1 failed, 1 passed in 0.05s ========================== ``` If pytest-queryguard hits an internal error, it stops recording and issues a `QueryGuardInternalWarning` that names the listener that failed; the session summary repeats it with the error and the line that raised it. A `record_queries()` block that ends after such an error then warns that its log may be incomplete (the warning class is exported from `pytest_queryguard`), and `log.assert_no_nplusone()` raises `RuntimeError` instead of passing on a log that may be empty. This also holds outside pytest and with `--queryguard-mode=off`. The warning is issued when the block ends normally; a block left by an exception does not warn, so the warning never replaces the exception, but its log is still fixed at that point and `assert_no_nplusone()` still refuses it. An "error" warnings filter does not turn this warning into an exception either. What is public API, and what is not, is defined on the [Stability and versioning](https://maciejziel.github.io/pytest-queryguard/stability.html) page. In short: the names in `pytest_queryguard.__all__` and the pytest options, markers and finding kinds are public; the constructors of `QueryLog`, `Query` and `CallSite` are not. `record_queries()` reads the queries; `max_queries()` and `max_db_time()` yield the same `QueryLog`, so `with max_queries(3) as log:` also gives `log.count`, `log.queries` and `log.slowest()`. The `queryguard` fixture gives a `QueryLog` from `queryguard.max_queries(n)` and `queryguard.num_queries(n)` blocks that counts only the statements of the test's own thread or asyncio task, and without `assert_no_nplusone()`, and the statements of the whole test as `queryguard.queries` (see [Budgets in a test with the `queryguard` fixture](https://maciejziel.github.io/pytest-queryguard/budgets.html#budgets-in-a-test-with-the-queryguard-fixture)). Recording changes nothing else. The plugin's N+1 detection, budgets and index check see the same statements. Like `max_queries()`, `record_queries()` also works outside pytest. ## The count must not grow: `assert_queries_do_not_grow()` Since 1.1.0. A list should send the same number of statements for 1 row as for 10. `assert_queries_do_not_grow(fn, sizes=(1, 10), *, setup=None)` runs `fn` once per size, each run in its own `record_queries()` block, and raises `QueryBudgetExceeded` when a statement (its shape without literals and parameters, its line and the relationship it loaded) runs more often at a larger size than at the smallest one: ```python from pytest_queryguard import assert_queries_do_not_grow from app.orders_fixed import list_orders def test_list_orders_does_not_grow(make_session): assert_queries_do_not_grow(list_orders, sizes=(1, 10, 50), setup=make_session) ``` - `sizes`: at least two different integers of 1 or more, run in ascending order (default `(1, 10)`). Not 0: code often returns early for no rows. Keep to 2 or 3 sizes: each runs the constant statements again in the same test, and 5 runs reach the plugin's repeat threshold. - `setup`: called with the size before `fn`, and not recorded; create that many rows there. `fn` gets what it returned. Without `setup`, `fn` gets the size. A generator, iterator or Django `QuerySet` that `fn` returns is iterated inside the block, so its queries count. - It returns the `QueryLog` of each size, keyed by size in ascending order. - The failure gives the count per size and each statement that grew (the same shape, without literals and parameters, from the same line): how often it ran at each size, the relationship it lazy-loaded, its line and the lines that called it, and a fix, like the N+1 report: for a lazy load, `joinedload()` or `selectinload()` with SQLAlchemy, `select_related()` or `prefetch_related()` with Django; for a query or a write in a loop, the same fix as the N+1 report. - Statements from any thread count, as in `record_queries()`. The seeding in `setup` is left out of the comparison, but the plugin still sees it as part of the test, so a default budget counts it. - `assert_queries_do_not_grow_async()` takes the same arguments and is awaited; `fn` and `setup` may be coroutine functions or plain functions, and what they return is awaited when it is awaitable. The sync version raises `TypeError` when `fn` or `setup` returns an awaitable. - After an internal error it raises `RuntimeError` instead of comparing counts that may be incomplete, like `assert_no_nplusone()`. The [scaling recipe](https://maciejziel.github.io/pytest-queryguard/recipes-query-count-scaling.html) shows it with SQLAlchemy and Django, and its failure. ## Leaving out a block: `ignore()` `ignore(*kinds, reason=None)` leaves out the findings of the given kinds that the code inside the block makes, for the plugin, for `log.assert_no_nplusone()` and for the [in-application mode](https://maciejziel.github.io/pytest-queryguard/in-app.html): ```python from pytest_queryguard import ignore with ignore("relationship-load", reason="one-off export"): export_report(session) @ignore("repeated-statement") def warm_cache(session): ... ``` - `kinds`: one or more finding kinds (`"relationship-load"`, `"repeated-statement"`, `"column-load"`, `"write-loop"`, `"unused-eager-load"`, `"unused-columns"`, `"cartesian-load"`, `"missing-index"`) or `fnmatch` patterns for them, such as `"*"`. None, or a pattern that matches no kind, raises `TypeError` or `ValueError`. - `reason`: a string for the reader; not used. It returns a context manager that is also a decorator, for a function or a coroutine function (a generator function raises `TypeError`, because the block would end before the generator runs). One object may be entered again, nested or from several tasks at once. Its class is not public: use it only through `ignore()`. A finding is left out only when everything it counts ran inside a block for its kind, in the thread or asyncio task that entered the block or in a task created inside it. Threads started inside the block are not covered unless they run in a copy of the context. A block that left out nothing in the whole run is listed as stale in the session summary. The details are in [Ignoring findings](https://maciejziel.github.io/pytest-queryguard/ignoring.html#the-ignore-block). --- Source: https://maciejziel.github.io/pytest-queryguard/in-app.html # In-application mode pytest-queryguard normally runs in your tests. The in-application mode runs the same N+1 rules and query budgets on every HTTP request of a running ASGI or WSGI application, so you see findings while you click through a development server or a staging environment. > **Development and staging only.** The mode adds work to every statement of > a watched engine, and the optional panel shows SQL text to anyone who can > reach it. Never enable either in production. The examples below switch it > on only when `APP_ENV` is `development`. It ships from 0.5.0 on. Its names, settings, reports and the panel's JSON follow the [deprecation policy](https://maciejziel.github.io/pytest-queryguard/stability.html#the-in-application-mode), as the pytest plugin does; only [findings in the page](https://maciejziel.github.io/pytest-queryguard/in-app.html#findings-in-the-page) (`page_report`) is still experimental. **In short:** call `queryguard.watch(engine)` at startup and add `QueryGuardASGI` (FastAPI, Starlette, any ASGI app) or `QueryGuardWSGI` (Flask, any WSGI app). Each request with a finding or over its budget logs a WARNING on the `pytest_queryguard.app` logger. Optional: a [panel](https://maciejziel.github.io/pytest-queryguard/in-app.html#the-panel) at `/_queryguard/`, [findings in the page](https://maciejziel.github.io/pytest-queryguard/in-app.html#findings-in-the-page), [OpenTelemetry and Sentry](https://maciejziel.github.io/pytest-queryguard/in-app.html#reporting-to-opentelemetry-and-sentry), and `track()` for jobs and tasks [outside HTTP](https://maciejziel.github.io/pytest-queryguard/in-app.html#outside-http). ## FastAPI and Starlette Watch the engine, add the middleware. A shortened version of `app/main.py` in [examples/in-app](https://github.com/MaciejZiel/pytest-queryguard/tree/main/examples/in-app), which also has the endpoints and a `demo.py` that sends requests to them: ```python import os from fastapi import FastAPI from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine from pytest_queryguard import app as queryguard engine = create_async_engine("sqlite+aiosqlite:///app.db") sessions = async_sessionmaker(engine, expire_on_commit=False) app = FastAPI() # Development only: never in production. if os.environ.get("APP_ENV") == "development": queryguard.watch(engine) app.add_middleware( queryguard.QueryGuardASGI, budgets={"GET /orders/{order_id}": 1}, panel=True, ) ``` `watch()` takes an `Engine` or an `AsyncEngine`, positionally (`watch(engine)`, not `watch(engine=engine)`). Call it at startup, before the engine hands out connections. `QueryGuardASGI` is plain ASGI middleware and does not import Starlette, so it also wraps any other ASGI 3 application: `app = queryguard.QueryGuardASGI(app)`. A request to the endpoint with a lazy-load loop logs a WARNING on the `pytest_queryguard.app` logger. This is the output of `python demo.py` in the example (FastAPI 0.141, Starlette 1.7, SQLAlchemy 2.1): ```text WARNING pytest_queryguard.app: queryguard: GET /orders: 6 statements queryguard: N+1 detected Order.customer was lazy-loaded 5 times first at app/main.py:48 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` `GET /orders/3` runs two statements against a budget of one: ```text WARNING pytest_queryguard.app: queryguard: GET /orders/3 (route /orders/{order_id}): 2 statements queryguard: expected at most 1 query, got 2 1. SELECT orders.id, orders.customer_id FROM orders WHERE orders.id = ? (app/main.py:64 in get_order) 2. SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/main.py:65 in get_order) database time: 226 us slowest: 127 us SELECT orders.id, orders.customer_id FROM orders WHERE orders.id = ? (app/main.py:64 in get_order) 99 us SELECT customer.id, customer.name FROM customer WHERE customer.id = ? (app/main.py:65 in get_order) ``` A request without findings and within its budget logs nothing. A request's `status` is the one in the response it sends. An endpoint that raises before sending one is reported with `500`. In Starlette and FastAPI, a handler for `500` or `Exception` (`@app.exception_handler(Exception)`) runs in Starlette's outermost `ServerErrorMiddleware`, outside every `add_middleware()` layer. The report then shows `500` even when that handler answers with another status, and the handler's statements are not counted. To include both, wrap the whole application instead of calling `add_middleware()`: `app = queryguard.QueryGuardASGI(app, ...)`. Handlers for other exceptions and statuses run inside the middleware and are reported as sent. ## Flask and other WSGI applications Wrap `app.wsgi_app`. WSGI has no route templates, so a `before_request` hook tells queryguard the Flask rule; without it, budgets match the request path. ```python import os from flask import Flask, request from sqlalchemy import create_engine from pytest_queryguard import app as queryguard engine = create_engine("sqlite:///app.db") app = Flask(__name__) # Development only: never in production. if os.environ.get("APP_ENV") == "development": queryguard.watch(engine) app.wsgi_app = queryguard.QueryGuardWSGI( app.wsgi_app, budgets={"GET /orders/": 1} ) @app.before_request def name_the_route() -> None: # WSGI has no route templates; tell queryguard the Flask rule. if request.url_rule is not None: queryguard.set_route(request.url_rule.rule) ``` With Flask-SQLAlchemy, the engines exist only inside an application context: ```python with app.app_context(): queryguard.watch(db.engine) # the default bind queryguard.watch(db.engines["audit"]) # a bind from SQLALCHEMY_BINDS ``` Only watched engines count. A bind you do not watch adds no statements and no findings to the request, even when one Session uses several binds. The same lazy-load loop in a Flask view: ```text WARNING pytest_queryguard.app: queryguard: GET /orders: 6 statements queryguard: N+1 detected Order.customer was lazy-loaded 5 times first at app/flask_app.py:41 in list_orders kind: relationship-load label: Order.customer docs: https://maciejziel.github.io/pytest-queryguard/how-detection-works.html#relationship-load sql: SELECT customer.id, customer.name FROM customer WHERE customer.id = ? fix: load it with the parent query, e.g. select(Order).options(joinedload(Order.customer)) ``` A WSGI request ends when its response body has been read to the end or closed, as every WSGI server does. Iterator initialization and response cleanup run in that request's context. When the body is exhausted, the middleware closes it before finalizing the report, so queries in cleanup callbacks (such as Flask's `Response.call_on_close`) count too. A later `close()` does not run those callbacks again. Because of that early close, an exception raised by the application's `close()` reaches the server from the last step of iteration instead of from the server's own `close()` call; the report is finalized either way. The Flask test client does neither on its own: read the body (`response.data`, `response.get_json()`), use `with client.get(...) as response:`, or pass `buffered=True`. When the server provides `wsgi.file_wrapper` and the application returns an object created by it (for example, a Flask `send_file()` response), queryguard returns that native object unchanged. The server can still recognize it for its optimized file transfer. Operations on the supplied file run in the request's context; the report ends when the server closes the native wrapper, including on a partial transfer or a response whose body is not read. Queries in the file's cleanup count too. File methods such as `fileno()`, `seek()` and `tell()` remain available. This does not enable a native transfer on servers that do not already support one. ## Outside HTTP `track()` measures any unit of work that is not a request: a job, a CLI command, a message handler, a task of Celery or RQ. Each unit is reported like a request, with its own budget (`default_budget`): ```python from pytest_queryguard import app as queryguard with queryguard.track("nightly export", default_budget=50) as report: ... # run the job print(report.statement_count, [f.label for f in report.findings]) ``` As a decorator, each call is a unit, named after the function unless a name is given. A coroutine function is measured across its awaits, a generator function over its whole iteration (its own statements, not those the code reading it runs between items), and `async with` works too: ```python @queryguard.track(default_budget=20) def export_invoices(month): ... @queryguard.track("orders consumer") async def handle(message): ... async with queryguard.track("sync accounts") as report: ... ``` Units in concurrent tasks or threads never mix: each counts the statements of its own context, also when they enter one shared `track()` object (a module-level `UNIT = queryguard.track("handler")`). ### Celery Decorate the task function under `@app.task`, or measure every task from the worker's signals, which run in the task's context: ```python from celery.signals import task_postrun, task_prerun from pytest_queryguard import app as queryguard queryguard.watch(engine) _units: dict[str, queryguard.track] = {} @task_prerun.connect def _start_unit(task_id, task, **_): unit = queryguard.track(task.name, default_budget=100) unit.start() _units[task_id] = unit @task_postrun.connect def _stop_unit(task_id, state=None, **_): unit = _units.pop(task_id, None) if unit is not None: unit.stop(failed=state != "SUCCESS") ``` `start()` and `stop()` are the two halves of the `with` block for code that cannot wrap the work in one: `stop()` returns the `RequestReport`, and `failed=True` keeps a warning turned into an error from being raised over the task's own failure. One object runs one such unit at a time; starting it again, or stopping it twice, raises `RuntimeError`. ### RQ RQ runs a job function by its import path, so decorating the function is enough: `@queryguard.track()` on the function the job names. Call `queryguard.watch(engine)` where the worker imports the application. ## Settings `QueryGuardASGI`, `QueryGuardWSGI` and `track()` take these as keyword arguments, or one `queryguard.Settings(...)` object as `settings=`. | Setting | Default | Meaning | |---|---|---| | `relationship_threshold` | 2 | Lazy loads of one relationship for different parents that count as N+1 | | `repeat_threshold` | 5 | Runs of one `SELECT` shape that count as N+1 | | `column_load_threshold` | 5 | Instances loading deferred or expired columns on their own | | `small_repeat_threshold` | None | Optional; as in the plugin | | `write_loop_threshold` | None | Optional; as in the plugin | | `scope` | `"request"` | `"request"`: everything in a request counts together; `"session"`: each Session on its own. Before 0.8.0 `repeat_scope`, which still works with a `QueryGuardDeprecationWarning` until 2.0 | | `budgets` | `{}` | `"METHOD path"` or `"path"` to the most statements a request may run | | `default_budget` | None | The budget of a request no key matches | | `report` | `"log"` | `"log"`, `"warn"`, a callable, or a list of them | | `max_events` | 1000 | Statements stored per request; more are counted, not stored | | `sample_rate` | 1.0 | Fraction of requests measured, from 0 to 1 | | `min_db_time` | 0.0 | Seconds of database time below which a request's N+1 rules do not run | | `page_report` | `"off"` | Since 0.8.0, experimental. `"footer"` or `"console"`: add a request's findings to its own HTML page (see [Findings in the page](https://maciejziel.github.io/pytest-queryguard/in-app.html#findings-in-the-page)) | The rules are the plugin's; see [How detection works](https://maciejziel.github.io/pytest-queryguard/how-detection-works.html). The missing-index check does not run in the application. **Budgets.** A key's path is an `fnmatch` pattern matched against the route template (`/orders/{order_id}` in FastAPI and Starlette, the rule given to `set_route()` in Flask) and against the request path; the first matching key wins, so put specific keys first: `{"GET /orders/{order_id}": 2, "/admin/*": 50}`. The method is the key's first word when it is letters and hyphens only; the rest of the key, spaces included, is the path (`"GET /files/my docs/*"`). In an application mounted inside another (`app.mount("/api", sub_app)`), the template is the one inside the mounted application, without the mount prefix; the request path keeps it. **Reports.** `report` is used only for requests with findings or over their budget. `"log"` writes one WARNING record. `"warn"` issues `queryguard.QueryGuardAppWarning`, a subclass of the plugin's `QueryGuardWarning`, which follows Python's warning filters: a filter for `pytest_queryguard.QueryGuardWarning` matches the findings of the plugin and of the application, one for `pytest_queryguard.app.QueryGuardAppWarning` only the application's. With `-W error::pytest_queryguard.app.QueryGuardAppWarning` it becomes an exception, raised when the request ends, and only when the application did not raise its own: the application's exception always wins, and the other targets still run. In an ASGI server the exception comes after the response has been sent, so the client gets the whole response and the server logs the error (uvicorn: `Exception in ASGI application`). A WSGI response has started before its report is ready, and an exception raised from its body would only cut it short (a chunked response loses its final chunk under gunicorn and waitress), so the WSGI middleware logs it instead: one ERROR record on `pytest_queryguard.app`, starting `QueryGuardAppWarning:`. `track()` raises it as usual. Every reported request warns: the `default` and `module` actions do not hide a repeated message, while `once` keeps every distinct message in Python's process-wide registry. A callable receives a `RequestReport` with `method`, `path`, `route`, `status`, `statements` (`Query` objects with `sql`, `callsite`, `relationship` and `duration`), `statement_count`, `db_time`, `duration`, `findings`, `budget`, `over_budget`, `truncated` (more statements than `max_events` stored), `problems`, `error` (an internal error made the report incomplete), `sampled` and `message`. Each of `findings` is a `queryguard.Finding` with `kind`, `label`, `file`, `function`, `line`, `count` and `message`, the keys the panel's JSON shows; its other attributes are internal (see [Stability](https://maciejziel.github.io/pytest-queryguard/stability.html#the-in-application-mode)). `statements` and `statement_count` are the names the panel's JSON, OpenTelemetry and Sentry use too; in a test, `QueryLog` calls the same `Query` objects `queries` and their number `count`. ```python from pytest_queryguard import app as queryguard def to_my_tracker(report: queryguard.RequestReport) -> None: for finding in report.findings: print(report.method, report.route or report.path, finding.kind, finding.label) middleware_options = {"report": ["log", to_my_tracker]} ``` An exception in a callable is logged and does not reach the request. Callables are called synchronously when the request ends, in the request's thread or on the event loop, so keep them fast: hand the report to a queue or schedule a task. A coroutine function (`async def`) is refused with a `ValueError` when the settings are made, since it would never be awaited. **Sampling and fast requests.** `sample_rate=0.1` measures one request in ten, chosen at random; the others run as if the middleware were not there (no collector, no report, not in the panel), and their statements cost the watched engine's listeners one `ContextVar.get()` each. A `track()` unit left out the same way yields a `RequestReport` with `sampled=False` and nothing in it; statements inside it still count for an enclosing request or unit that was measured. `min_db_time=0.005` skips the N+1 rules for a request whose database time was below 5 ms. The value compares `RequestReport.db_time`: the summed duration of every statement the request ran on watched engines, stored or only counted, from the cursor execute to its end (a statement that raises adds nothing). It is not the time of the finding's own statements, which queryguard does not total: an N+1 of five fast lazy loads in a request with one slow query is still reported. Such a request has no findings, and it is reported only when it is over its budget; budgets do not depend on `min_db_time`. ## Reporting to OpenTelemetry and Sentry Two ready-made `report` callables send findings to the tools you may already watch. Each imports its library when you create it, so a missing package raises `ImportError` at startup; neither library is a dependency of pytest-queryguard. Like any callable, an exception inside one (a Sentry outage) is logged and does not reach the request. ```python from pytest_queryguard import app as queryguard app.add_middleware( queryguard.QueryGuardASGI, report=[ "log", queryguard.opentelemetry_reporter(), queryguard.sentry_reporter(), ], ) ``` `opentelemetry_reporter()` (needs `opentelemetry-api`) writes to the span that is current when the request ends (for a `track()` unit, the span around the block), so the OpenTelemetry instrumentation must wrap the queryguard middleware: wrap the `OpenTelemetryMiddleware` of the ASGI or WSGI instrumentation around it, or instrument FastAPI with `FastAPIInstrumentor` after adding queryguard. Nothing is written when no span is recording, for example when the request's span has already ended. A WSGI request read to the end is reported while its body is iterated; one closed before its end is reported from `close()`, which the WSGI instrumentation may call outside its span, so such a report can miss it. The span gets the attributes `queryguard.statement_count`, `queryguard.db_time` (seconds), `queryguard.findings` (how many), `queryguard.budget` (when there is one) and `queryguard.over_budget`; each finding adds a `queryguard.finding` event with `queryguard.kind`, `queryguard.label`, `queryguard.file`, `queryguard.line`, `queryguard.function`, `queryguard.count` and `queryguard.fingerprint`, and a request over budget a `queryguard.budget` event with `queryguard.budget` and `queryguard.statement_count`. Attributes without a value (a finding with an unknown call site) are left out. `sentry_reporter(level="warning")` (needs `sentry-sdk`, initialized with `sentry_sdk.init()` as usual) sends one `capture_message` per finding, titled `queryguard: