Skip to main content

Django-compatible session for async frameworks

Project description

Async Django Session

It gives you ability to share session between django and an async framework like aiohttp, starlette, fastapi etc.

pip install async-django-session



There's two ways of communicating to database available:

  • through databases - which is compatible with most of major RDBMS:
    database = databases.Database(DB_URI)
    await database.connect()
    backend = async_django_session.databases.Backend(database, SECRET_KEY)
  • or directly through asyncpg (PostgreSQL only):
    pool = await asyncpg.create_pool(DB_URI)
    backend = async_django_session.asyncpg.Backend(pool, SECRET_KEY)


To fetch session from db by its key there's backend.get_session method. If key is None a new session will be created:

session = backend.get_session(key)

It's lazy so the session data won't be actually fetched until you call its load method. In caches the result, so it's inexpensive to call it multiple times:

await session.load()

You can combine them into a single line as the load method returns session itself:

session = await backend.get_session(key).load()

Session provides dict-interface to read / write data:

session["foo"] = "bar"

To sync session with database you should explicitly call its save method. It won't make unnecessary db call if the session wasn't changed (the boolean value it returns is intend to indicate if it was the case).

saved = await

During saving of a new session a random key will be generated and available as session.key parameter afterwords.

Frameworks integration

There's built-in middlewares for a few frameworks to automatically load (using session id from cookies) and save sessions.


After adding of session middleware:

session_middleware = async_django_session.aiohttp.middleware(
    async_django_session.databases.Backend(db, SECRET_KEY)
app = web.Application(middlewares=[session_middleware])

You can get requests session as:

session = await request.get_session()

A full aiohttp example can be found here.


After adding of session middleware:

    app, async_django_session.databases.Backend(db, SECRET))

Session of a current request is available as:

session = await request.state.get_session()

A working starlette example is here.


Perform starlette app initialization from above as fastapi based on it. After that you can get session using dependency injection as:

from async_django_session.fastapi import get_session
from async_django_session.session import Session

async def index(session: Session = Depends(get_session)):

A working fastapi example is here.

Running examples

Running the examples you can see different frameworks using the same session data. To see session data open http://localhost:8000/ after running of each example.

Install requirements:

cd examples
pip install -r requirements.txt

Create database and tables:

createdb async_django_session
python migrate

Run aiohttp example which uses databases backend:


Run starlette example which uses asyncpg backend:


Run fastapi example which uses asyncpg backend:


Run django example:

python runserver

Project details

Download files

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

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page