https://github.com/krylosov-aa/context-async-sqlalchemy
A convenient way to configure and work with an async SQLAlchemy session through context in asynchronous applications
https://github.com/krylosov-aa/context-async-sqlalchemy
asgi asgi-middleware async asynchronous asyncio context contextvars fastapi fastapi-boilerplate fastapi-sqlalchemy ioc ioc-container python python3 sql sqlalchemy sqlalchemy-async sqlalchemy-python sqlalchemy2 starlette
Last synced: about 11 hours ago
JSON representation
A convenient way to configure and work with an async SQLAlchemy session through context in asynchronous applications
- Host: GitHub
- URL: https://github.com/krylosov-aa/context-async-sqlalchemy
- Owner: krylosov-aa
- License: mit
- Created: 2025-11-09T06:40:13.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T21:32:15.000Z (3 months ago)
- Last Synced: 2026-01-13T01:46:40.336Z (3 months ago)
- Topics: asgi, asgi-middleware, async, asynchronous, asyncio, context, contextvars, fastapi, fastapi-boilerplate, fastapi-sqlalchemy, ioc, ioc-container, python, python3, sql, sqlalchemy, sqlalchemy-async, sqlalchemy-python, sqlalchemy2, starlette
- Language: Python
- Homepage: https://krylosov-aa.github.io/context-async-sqlalchemy/
- Size: 3.42 MB
- Stars: 54
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# context-async-sqlalchemy
[](https://pypi.org/project/context-async-sqlalchemy/)
[](https://pepy.tech/projects/context-async-sqlalchemy)
[](https://github.com/krylosov-aa/context-async-sqlalchemy/actions/workflows/tests.yml) (coverage > 90%)
[DOCUMENTATION](https://krylosov-aa.github.io/context-async-sqlalchemy/)
Provides a super convenient way to work with SQLAlchemy in asynchronous
applications.
It handles the lifecycle management of the engine, sessions, and
transactions.
The main goal is to provide quick and easy access to a session,
without worrying about opening or closing it when it’s not necessary.
Key features:
- Automatically manages the lifecycle of the engine, sessions, and
transactions
- Allows for user autonomy when manually opening or closing sessions and
transactions
- Framework-agnostic
- Not a wrapper around SQLAlchemy
- Convenient for testing
- Runtime host switching
- Supports multiple databases and sessions per database
- Provides tools for running concurrent SQL queries
- Fully lazy initialization
## Example of a typical session
```python
from context_async_sqlalchemy import db_session
from sqlalchemy import insert
from database import connection # your configured connection to the database
from models import ExampleTable # a model for example
async def some_func() -> None:
# Creates a session with no connection to the database yet
session = await db_session(connection)
stmt = insert(ExampleTable).values(text="example_with_db_session")
# A connection and transaction open in the first request.
await session.execute(stmt)
# If you call db_session again, it returns the same session
# even in child coroutines.
session = await db_session(connection)
# The second request uses the same connection and the same transaction
await session.execute(stmt)
# The commit and closing of the session occurs automatically
```
## How it works
1. Before executing your code, the middleware prepares a container in
which the sessions required by your code are stored.
The container is saved in `contextvars`.
2. Your code accesses the library to create new sessions and retrieve
existing ones.
3. The middleware automatically commits or rolls back open
transactions. It also closes open sessions and clears the context.
The library provides the ability to commit, roll back, and close at any