docs: document asyncio support (#32)

Author: hadrien

README.md

@@ -8,11 +8,15 @@ A highly opinionated [SQLAlchemy] extension for [FastAPI]:
 
 * Setup using environment variables to connect on DB;
 * `fastapi_sqla.Base` a declarative base class to reflect DB tables at startup;
-* `fastapi_sqla.with_session` a dependency to get an sqla session;
+* `fastapi_sqla.Session` a dependency to get an sqla session;
+* `fastapi_sqla.open_session` a context manager to get an sqla session;
+* `fastapi_sqla.async_support.AsyncSession` a dependency to get an async sqla session ;
+* `fastapi_sqla.async_support.open_session` a context manager to get an async sqla
+  session;
 * Automated commit/rollback of sqla session at the end of request before returning
   response;
 * Pagination utilities;
-* Pytest fixtures to easy writing test;
+* Pytest fixtures;
 
 ## Configuration
 
@@ -25,6 +29,21 @@ call.
 
 The only required key is `sqlalchemy_url`, which provides the database URL.
 
+#### `asyncio` support using [`asyncpg`]
+
+SQLAlchemy `>= 1.4` supports `asyncio`.
+To enable `asyncio` support against a Postgres DB, install `asyncpg`:
+
+```bash
+pip install asyncpg
+```
+
+And define environment variable `async_sqlalchemy_url` with `postgres+asyncpg` scheme:
+
+```bash
+export async_sqlalchemy_url=postgresql+asyncpg://postgres@localhost
+```
+
 ### Setup the app:
 
 ```python
@@ -59,13 +78,19 @@ exception occurred:
 ```python
 from fastapi import APIRouter, Depends
 from fastapi_sqla import Session
+from fastapi_sqla.asyncio_support import AsyncSession
 
 router = APIRouter()
 
 
 @router.get("/example")
 def example(session: Session = Depends()):
     return session.execute("SELECT now()").scalar()
+
+
+@router.get("/async_example")
+async def async_example(session: AsyncSession = Depends()):
+    return await session.execute("SELECT now()").scalar()
 ```
 
 #### Using a context manager
@@ -78,18 +103,25 @@ occurred:
 ```python
 from fastapi import APIRouter, BackgroundTasks
 from fastapi_sqla import open_session
+from fastapi_sqla import asyncio_support
 
 router = APIRouter()
 
 
 @router.get("/example")
 def example(bg: BackgroundTasks):
     bg.add_task(run_bg)
+    bg.add_task(run_async_bg)
 
 
 def run_bg():
     with open_session() as session:
         session.execute("SELECT now()").scalar()
+
+
+async def run_async_bg():
+    async with asyncio_support.open_session() as session:
+        await session.execute("SELECT now()").scalar()
 ```
 
 ### Pagination
@@ -238,13 +270,23 @@ def db_url():
     return "postgresql://postgres@localhost/test_database"
 ```
 
+### `async_sqlalchemy_url`
+
+DB url to use when using `asyncio` support. Defaults to `db_url` fixture with
+`postgresql+asyncpg://` scheme.
 
-### `session`
 
-Sqla session to create db fixture:
+### `session` & `async_session`
+
+Sqla sessions to create db fixture:
 * All changes done at test setup or during the test are rollbacked at test tear down;
 * No record will actually be written in the database;
-* Changes in one session need to be committed to be available from other sessions;
+* Changes in one regular session need to be committed to be available from other regular
+  sessions;
+* Changes in one async session need to be committed to be available from other async
+  sessions;
+* Changes from regular sessions are not available from `async` session and vice-versa
+  even when committed;
 
 Example:
 ```python
@@ -258,6 +300,15 @@ def patient(session):
     session.add(patient)
     session.commit()
     return patient
+
+
+@fixture
+async def doctor(async_session):
+    from er.sqla import Doctor
+    doctor = Doctor(name="who")
+    async_session.add(doctor)
+    await async_session.commit()
+    return doctor
 ```
 
 ### `db_migration`
@@ -307,3 +358,4 @@ It returns the path of  `alembic.ini` configuration file. By default, it returns
 [FastAPI dependency injection]: https://fastapi.tiangolo.com/tutorial/dependencies/
 [FastAPI background tasks]: https://fastapi.tiangolo.com/tutorial/background-tasks/
 [SQLAlchemy]: http://sqlalchemy.org/
+[`asyncpg`]: https://magicstack.github.io/asyncpg/current/

fastapi_sqla/__init__.py

@@ -11,12 +11,17 @@
 from pydantic import BaseModel, Field
 from pydantic.generics import GenericModel
 from sqlalchemy import engine_from_config
-from sqlalchemy.ext.declarative import DeferredReflection, declarative_base
+from sqlalchemy.ext.declarative import DeferredReflection
 from sqlalchemy.orm import Query as LegacyQuery
 from sqlalchemy.orm.session import Session as SqlaSession
 from sqlalchemy.orm.session import sessionmaker
 from sqlalchemy.sql import Select, func, select
 
+try:
+    from sqlalchemy.orm import declarative_base
+except ImportError:
+    from sqlalchemy.ext.declarative import declarative_base
+
 try:
     from . import asyncio_support
     from .asyncio_support import AsyncSession
@@ -47,8 +52,8 @@ def setup(app: FastAPI):
     app.add_event_handler("startup", startup)
     app.middleware("http")(add_session_to_request)
 
-    asyncpg_url = os.getenv("asyncpg_url")
-    if asyncpg_url:
+    async_sqlalchemy_url = os.getenv("async_sqlalchemy_url")
+    if async_sqlalchemy_url:
         assert asyncio_support, asyncio_support_err
         app.add_event_handler("startup", asyncio_support.startup)
         app.middleware("http")(asyncio_support.add_session_to_request)

fastapi_sqla/_pytest_plugin.py

@@ -4,7 +4,7 @@
 from alembic import command
 from alembic.config import Config
 from pytest import fixture
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, text
 
 try:
     from sqlalchemy.ext.asyncio import create_async_engine
@@ -27,12 +27,6 @@ def db_url():
     return f"postgresql://postgres@{host}/postgres"
 
 
-@fixture(scope="session")
-def asyncpg_url(db_url):
-    scheme, parts = db_url.split(":")
-    return f"{scheme}+asyncpg:{parts}"
-
-
 @fixture(scope="session")
 def sqla_connection(db_url):
     engine = create_engine(db_url)
@@ -56,7 +50,7 @@ def db_migration(db_url, sqla_connection, alembic_ini_path):
     alembic_config = Config(file_=alembic_ini_path)
     alembic_config.set_main_option("sqlalchemy.url", db_url)
 
-    sqla_connection.execute("DROP SCHEMA public CASCADE; CREATE SCHEMA public;")
+    sqla_connection.execute(text("DROP SCHEMA public CASCADE; CREATE SCHEMA public;"))
 
     command.upgrade(alembic_config, "head")
     yield
@@ -110,15 +104,27 @@ def session(sqla_transaction, sqla_connection):
 
 if asyncio_support:
 
+    @fixture(scope="session")
+    def async_sqlalchemy_url(db_url):
+        """Default async db url.
+
+        It is the same as `db_url` with `postgresql+asynpg://` as scheme.
+        """
+        scheme, parts = db_url.split(":")
+        return f"{scheme}+asyncpg:{parts}"
+
+    @fixture
+    async def async_engine(async_sqlalchemy_url):
+        return create_async_engine(async_sqlalchemy_url)
+
     @fixture
-    async def async_sqla_connection(asyncpg_url, event_loop):
-        engine = create_async_engine(asyncpg_url)
-        async with engine.begin() as connection:
+    async def async_sqla_connection(async_engine, event_loop):
+        async with async_engine.begin() as connection:
             yield connection
             await connection.rollback()
 
     @fixture(autouse=True)
-    async def patch_async_sessionmaker(asyncpg_url, async_sqla_connection):
+    async def patch_async_sessionmaker(async_sqlalchemy_url, async_sqla_connection):
         """So that all async DB operations are never written to db for real."""
         with patch(
             "fastapi_sqla.asyncio_support.create_async_engine"

fastapi_sqla/asyncio_support.py

@@ -13,8 +13,8 @@
 
 
 def startup():
-    asyncpg_url = os.environ["asyncpg_url"]
-    async_engine = create_async_engine(asyncpg_url)
+    async_sqlalchemy_url = os.environ["async_sqlalchemy_url"]
+    async_engine = create_async_engine(async_sqlalchemy_url)
     _AsyncSession.configure(bind=async_engine, expire_on_commit=False)