Skip to main content

Detecting the n+1 queries problem in Python

Project description

Latest version Travis-CI Code coverage

nplusone is a library for detecting the n+1 queries problem in Python ORMs, including SQLAlchemy, Peewee, and the Django ORM.

The Problem

Many object-relational mapping (ORM) libraries default to lazy loading for relationships. This pattern can be efficient when related rows are rarely accessed, but quickly becomes inefficient as relationships are accessed more frequently. In these cases, loading related rows eagerly using a JOIN can be vastly more performant. Unfortunately, understanding when to use lazy versus eager loading can be challenging: you might not notice the problem until your app has slowed to a crawl.

nplusone is an ORM profiling tool to help diagnose and improve poor performance caused by inappropriate lazy loading. nplusone monitors applications using Django or SQLAlchemy and sends warnings when potentially expensive lazy loads are emitted. It can identify the offending relationship attribute and specific lines of code behind the problem, and recommend fixes for better performance.


pip install -U nplusone

nplusone supports Python >= 2.7 or >= 3.3.


Note: nplusone should only be used for development and should not be deployed to production environments.


Add nplusone to INSTALLED_APPS


Add NPlusOneMiddleware


Optionally configure logging settings

NPLUSONE_LOGGER = logging.getLogger('nplusone')

When your app loads data lazily, nplusone will emit a warning

Potential n+1 query detected on `<model>.<field>`

Consider using select_related or prefetch_related in this case.


Wrap application with NPlusOne

from flask import Flask
from nplusone.ext.flask_sqlalchemy import NPlusOne

app = Flask(__name__)

Optionally configure logging settings

app = Flask(__name__)
app.config['NPLUSONE_LOGGER'] = logging.getLogger('app.nplusone')
app.config['NPLUSONE_LOG_LEVEL'] = logging.ERROR

When your app loads data lazily, nplusone will emit a warning

Potential n+1 query detected on `<model>.<field>`

Consider using subqueryload or joinedload in this case; see SQLAlchemy’s guide to relationship loading for complete documentation.

Ignoring Warnings

To suppress warnings thrown by intentional lazy loading, use the ignore context manager

from nplusone.core import signals

with signals.ignore():
    # lazy-load rows
    # ...


MIT licensed. See the bundled LICENSE file for more details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nplusone-0.1.0.tar.gz (6.4 kB view hashes)

Uploaded source

Built Distribution

nplusone-0.1.0-py2.py3-none-any.whl (10.6 kB view hashes)

Uploaded 3 4

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page