Integrations

Application integration

Databasez has several ways to integrate in applications. Mainly recommended are the async contextmanager one and the asgi based.

AsyncContextManager

The recommended way of manually using databasez is via the async contextmanager protocol. This way it is ensured that the database is torn down on errors.

Luckily starlette based apps support the lifespan protocol (startup, teardown of an ASGI server) via async contextmanagers.

import contextlib

from starlette.applications import Starlette

from databasez import Database

database = Database("sqlite:///foo.sqlite")


@contextlib.asynccontextmanager
async def lifespan(app):
    async with database:
        yield


application = Starlette(
    lifespan=lifespan,
)

Note

This works also in different domains which are not web related.

ASGI

This is a lifespan protocol interception shim for ASGI lifespan. Instead of using the lifespan parameter of starlette, it is possible to wrap the ASGI application via the shim. This way databasez intercepts lifespans requests and injects its code. By default it passes the lifespan request further down, but it has a compatibility option named handle_lifespan. It is required for ASGI apps without lifespan support like django.

from django.core.asgi import get_asgi_application

from databasez import Database

applications = Database("sqlite:///foo.sqlite").asgi(
    # except you have a lifespan handler in django
    handle_lifespan=True
)(get_asgi_application())

Manually

Some Server doesn't support the lifespan protocol. E.g. WSGI based servers. As well as with the AsyncContextManager we are not limited to web applications. For demonstration purposes we use here esmerald with on_startup and on_shutdown events.

from esmerald import Esmerald

from databasez import Database

database = Database("sqlite:///foo.sqlite")


app = Esmerald(routes=[])


@app.on_event("startup")
async def startup():
    await database.connect()


@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

Note

Starlette is deprecating the integration via events. If you like this way and wants to keep it you may can switch to Esmerald, which continues to support the old way of integration or to use Starlette Bridge which enables such behavior and is from the same author. Starlette Bridge works for Starlette and any Starlette related project, for example, FastAPI.

ORMs

There are at least two ORMs using databasez:

• Edgy - A re-development of saffier using pydantic. It is very fast and has more features than saffier. It is the recommended ORM.
• Saffier - A stable workhorse but most development will happen now in edgy.

When using edgy, use the helpers of edgy instead of the ones of databasez for integrating in applications. This way you get all features of edgy's Registry.

Links