Metadata-Version: 2.4
Name: context-async-sqlalchemy
Version: 2.0.1
Summary: A convenient way to configure and interact with a async sqlalchemy session through context in asynchronous applications
Project-URL: Homepage, https://github.com/krylosov-aa/context-async-sqlalchemy
Author-email: krylosov-aa <krylosov.andrew@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: sqlalchemy>=2.0
Description-Content-Type: text/markdown

# context-async-sqlalchemy

[![PyPI](https://img.shields.io/pypi/v/context-async-sqlalchemy.svg)](https://pypi.org/project/context-async-sqlalchemy/)

[DOCUMENTATION](https://krylosov-aa.github.io/context-async-sqlalchemy/)

Provides a super convenient way to work with sqlalchemy in asynchronous
applications. It takes care of the issues of managing the lifecycle of engine,
session, and transactions without being a wrapper.

The main task is to get quick and easy access to the session and not worry
about when to open and when to close it.

The key features are:

- Super easy to use
- Automatically manages the lifecycle of engine, session, and transaction
(autocommit/autorollback)
- It doesn't interfere with manually opening and closing sessions and
transactions when needed.
- Does not depend on the web framework
- It is not a wrapper over sqlalchemy
- It is convenient to test
- Host switching in runtime
- It can manage multiple databases and multiple sessions to a single database
- Provides tools for concurrent sql queries
- Lazy initialization is everywhere


## What does usage look like?

```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  # just some model for example

async def some_func() -> None:
    # Created a session (no connection to the database yet)
    session = await db_session(connection)
    
    stmt = insert(ExampleTable).values(text="example_with_db_session")

    # On the first request, a connection and transaction were opened
    await session.execute(stmt)
    
    # If you call db_session again, it will return the same session
    # even in child coroutines.
    session = await db_session(connection)
    
    # The second request will use the same connection and the same transaction
    await session.execute(stmt)

    # The commit and closing of the session will occur automatically
```

## How it works

Here is a very simplified diagram of how everything works:

![basic schema.png](https://github.com/krylosov-aa/context-async-sqlalchemy/blob/main/docs_sources/docs/img/basic_schema.png)

1. Before executing your code, the middleware will prepare a container in
which the sessions required by your code will be stored.
The container is saved in contextvars
2. Your code accesses the library to create new sessions and retrieve
existing ones
3. After your code, middleware will automatically commit or roll back open
transactions. Closes open sessions and clears the context.

The library also provides the ability to commit, rollback, and close at any
time, without waiting for the end of the request, without any problems.
