Async Django ORM (Django Async Backend)

Async Django ORM and PostgreSQL database backend.

Django's a-prefixed ORM methods (aget, acreate, …) are thin sync_to_async wrappers: the query still runs on a threadpool, on a synchronous connection. django-async-backend replaces the database layer itself, so queries are issued on a real asyncio connection through psycopg 3, with async transactions, async cursors and optional connection pooling — no thread emulation.

The project is production ready: the API is stable, and each release is pinned to the Django feature release it was generated against, so upgrades stay predictable.

📖 Read the documentation

Compatibility

The package tracks Django's major and minor version, so the release you install is pinned to the Django feature release it was generated against.

Part of the ORM layer is generated from Django's own source, so a Django feature release gets a matching django-async-backend feature release rather than a loosened version range. Patch releases within a line are ordinary bugfix releases and are safe to upgrade to.

[!IMPORTANT] Run this under ASGI. django-async-backend is developed for ASGI, and that is the only mode it is supported in. Under WSGI — including the Django development server — it behaves inconsistently, because WSGI creates a new event loop for each request and the async connection state cannot be managed reliably across them. Connection pooling in particular is not supported there.

Installation

pip install django-async-backend[binary]

The binary extra installs the C-accelerated psycopg implementation. Without it you get the pure-Python implementation, which is noticeably slower. If you use connection pooling, add the pool extra as well:

pip install django-async-backend[binary,pool]

The package tracks Django's major and minor version — for example 6.0.x matches Django 6.0 — because a large part of the ORM layer is generated from Django's own source.

Quick start

# settings.py
DATABASES = {
    "default": {
        "ENGINE": "django_async_backend.db.backends.postgresql",
        ...
    },
}

INSTALLED_APPS = [
    ...
    "django_async_backend",
]

from django.db import models
from django_async_backend.db import async_connections
from django_async_backend.db.models.base import AsyncModelMixin
from django_async_backend.db.transaction import async_atomic


class Book(AsyncModelMixin, models.Model):
    name = models.CharField(max_length=100)


async def notify(book_id: int) -> None:
    ...


async def main() -> None:
    connection = async_connections["default"]

    async with async_atomic():
        book = await Book.async_objects.acreate(name="Django")

        # async callbacks are supported; runs only if the transaction commits
        await connection.on_commit(lambda: notify(book.pk))

        book.name = "Django Async"
        await book.async_save(update_fields=["name"])

        async with async_atomic():  # savepoint
            await Book.async_objects.filter(name="draft").adelete()

    print(await Book.async_objects.acount())

    async for row in Book.async_objects.order_by("name"):
        print(row.pk, row.name)

Or drop to a raw async cursor:

async with await connection.cursor() as cursor:
    await cursor.execute("SELECT id, name FROM app_book ORDER BY name")

    print(cursor.rowcount)

    async for row in cursor:
        print(row)

[!WARNING] Async does not mean parallel. A task gets one connection per database alias, and every ORM and cursor call in that task takes turns on it — so awaiting several queries in a row does not make them run concurrently.

The connection is owned by the task that first used it, so you cannot fan out onto it either: using it from another task — asyncio.create_task(), asyncio.gather(), asyncio.TaskGroup — raises RuntimeError. Wrapping the fan-out in a single async_atomic() block does not make it safe. To run queries in parallel, give each task its own connection with async_new_connection — sparingly, since each call opens a real connection and a wide fan-out can exhaust the server's limit.

Supported methods

Legend: ✅ supported · ❌ not supported · ⚠️ supported with caveats

QuerySet methods

Dunder methods

Model methods

RawQuerySet

Not supported ❌

Related managers

Not supported ❌ — instance.<related>.all() is the sync ORM. See Pitfalls.