Setup

FastSQLA provides two ways to configure your SQLAlchemy database connection:

• Environment variables (lifespan): Simple configuration following 12-factor app principles, ideal for most use cases.
• Programmatic (new_lifespan): Direct SQLAlchemy engine configuration for advanced customization needs

fastsqla.lifespan

Use fastsqla.lifespan to set up SQLAlchemy directly from environment variables.

In an ASGI application, lifespan events are used to communicate startup & shutdown events.

The lifespan parameter of the FastAPI app can be assigned to a context manager, which is opened when the app starts and closed when the app stops.

In order for FastSQLA to setup SQLAlchemy before the app is started, set lifespan parameter to fastsqla.lifespan:

from fastapi import FastAPI
from fastsqla import lifespan


app = FastAPI(lifespan=lifespan)

If multiple lifespan contexts are required, create an async context manager function to handle them and set it as the app's lifespan:

from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastsqla import lifespan as fastsqla_lifespan
from this_other_library import another_lifespan


@asynccontextmanager
async def lifespan(app:FastAPI) -> AsyncGenerator[dict, None]:
    async with AsyncExitStack() as stack:
        yield {
            **stack.enter_async_context(lifespan(app)),
            **stack.enter_async_context(another_lifespan(app)),
        }


app = FastAPI(lifespan=lifespan)

To learn more about lifespan protocol:

• Lifespan Protocol
• Use Lifespan State instead of app.state
• FastAPI lifespan documentation

Lifespan configuration

Configuration is done exclusively via environment variables, adhering to the Twelve-Factor App methodology.

The only required key is SQLALCHEMY_URL, which defines the database URL. It specifies the database driver in the URL's scheme and allows embedding driver parameters in the query string. Example:

sqlite+aiosqlite:////tmp/test.db

All parameters of sqlalchemy.create_engine can be configured by setting environment variables, with each parameter name prefixed by SQLALCHEMY_.

Note

FastSQLA is case-insensitive when reading environment variables, so parameter names prefixed with SQLALCHEMY_ can be provided in any letter case.

Examples

1. PostgreSQL url using asyncpg driver with a pool_recycle of 30 minutes:

   export SQLALCHEMY_URL=postgresql+asyncpg://postgres@localhost/postgres
   export SQLALCHEMY_POOL_RECYCLE=1800
   

2. SQLite db file using aiosqlite driver with a pool_size of 50:

   export sqlalchemy_url=sqlite+aiosqlite:///tmp/test.db
   export sqlalchemy_pool_size=50
   

3. MariaDB url using aiomysql driver with echo parameter set to True

   export sqlalchemy_url=mysql+aiomysql://bob:password!@db.example.com/app
   export sqlalchemy_echo=true
   

fastsqla.new_lifespan

Create a new lifespan async context manager.

It expects the exact same parameters as sqlalchemy.ext.asyncio.create_async_engine

Example:

from fastapi import FastAPI
from fastsqla import new_lifespan

lifespan = new_lifespan(
    "sqlite+aiosqlite:///app/db.sqlite", connect_args={"autocommit": False}
)

app = FastAPI(lifespan=lifespan)

Parameters:

Name	Type	Description	Default
url	str	Database url.	None
kw	dict	Configuration parameters as expected by sqlalchemy.ext.asyncio.create_async_engine	{}