sqlalchemy-triopg

A thin Trio-backed wrapper for SQLAlchemy's asyncpg PostgreSQL driver.

This wrapper is named after the existing raw asyncpg wrapper triopg, but does not actually use it. If you want to use asyncpg directly, use that package instead.

$ pdm add sqlalchemy-triopg
# or
$ pip install --user sqlalchemy-triopg

Usage

SQLAlchemy is able to automatically discover the dialect available through this package as soon as you install it. When creating your engine, just pass the triopg driver like so:

engine = create_async_engine("triopg://postgres:password@db/postgres")

Requisites

This package uses the trio-asyncio package to provide a compatibility layer with asyncio; it is what enables the "wrapping" in favor of just a re-implementation. However it also means that your program needs to ensure the Trio event loop is running, either via manually calling your program with trio_asyncio.run or by wrapping your main coroutine definition in trio_asyncio.open_loop.

For many projects like web apps, the terminal command for starting the application does not let you change how to start the ASGI server. Aside from creating a custom worker class and specifying it (like a custom Hypercorn or Gunicorn worker), you'll need to create a bootstrapping script where you can manually call trio_asyncio.run to your server's API.

This is because, unfortunately, binding an async context manager to the lifecycle of your application (a feature supported by both BlackSheep and FastAPI) in which you call trio_asyncio.open_loop doesn't seem to work.

Using Hypercorn's API, an example boot.py script could look like this:

#!/bin/python

import trio_asyncio
from hypercorn.config import Config
from hypercorn.trio import serve

from application import app

if __name__ == "__main__":
    trio_asyncio.run(serve, app, Config.from_toml("application.toml"))

Considerations

This package uses trio-asyncio, and you'll need to take that into account if you're combining Trio and existing asyncio tooling. If those tools do not use a bridge library like anyio, it's very likely that you'll need to extend them the coroutines by wrapping them in trio_asyncio.aio_as_trio (or using it as a decorator on your own coroutine functions).

This is an intentional anti-feature of trio-asyncio.

License

This package makes use of SQLAlchemy and Trio-Asyncio, both of which are licensed under MIT.

This package is licensed under the BSD 3-Clause Clear License.

This package is Treeware. If you use it in production, consider buying the world a tree to thank me for my work. By contributing to my forest, you’ll be creating employment for local families and restoring wildlife habitats.