Async Django ORM (Django Async Backend)

Async Django ORM and PostgreSQL database backend.

📖 Read the documentation

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",
]

# Required under ASGI so connections are released each request.
MIDDLEWARE = [
    "django_async_backend.middleware.close_async_connections",
    ...
]

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. Within one async context, all ORM and cursor calls share a single connection per database alias, so queries are serialized even under asyncio.gather(). This mirrors Django's DEP 0009.

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.