# FastSQLA
*Async SQLAlchemy 2.0+ for FastAPI — boilerplate, pagination, and seamless session management.*
**Documentation**:
**Github Repo:**
______________________________________________________________________
`FastSQLA` is an async [`SQLAlchemy 2.0+`](https://docs.sqlalchemy.org/en/20/) extension for [`FastAPI`](https://fastapi.tiangolo.com/) with built-in pagination, [`SQLModel`](http://sqlmodel.tiangolo.com/) support and more.
It streamlines the configuration and asynchronous connection to relational databases by providing boilerplate and intuitive helpers. Additionally, it offers built-in customizable pagination and automatically manages the `SQLAlchemy` session lifecycle following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
## Features
- Easy setup at app startup using [`FastAPI` Lifespan](https://fastapi.tiangolo.com/advanced/events/#lifespan):
```
from fastapi import FastAPI
from fastsqla import lifespan
app = FastAPI(lifespan=lifespan)
```
- `SQLAlchemy` async session dependency:
```
...
from fastsqla import Session
from sqlalchemy import select
...
@app.get("/heros")
async def get_heros(session:Session):
stmt = select(...)
result = await session.execute(stmt)
...
```
- `SQLAlchemy` async session with an async context manager:
```
from fastsqla import open_session
async def background_job():
async with open_session() as session:
stmt = select(...)
result = await session.execute(stmt)
...
```
- Built-in pagination:
```
...
from fastsqla import Page, Paginate
from sqlalchemy import select
...
@app.get("/heros", response_model=Page[HeroModel])
async def get_heros(paginate:Paginate):
return await paginate(select(Hero))
```
👇 `/heros?offset=10&limit=10` 👇
```
{
"data": [
{
"name": "The Flash",
"secret_identity": "Barry Allen",
"id": 11
},
{
"name": "Green Lantern",
"secret_identity": "Hal Jordan",
"id": 12
}
],
"meta": {
"offset": 10,
"total_items": 12,
"total_pages": 2,
"page_number": 2
}
}
```
- Pagination customization:
```
from typing import Annotated
from fastapi import Depends
from fastsqla import Page, PaginateType, new_pagination
CustomPaginate = Annotated[
PaginateType[HeroModel],
Depends(new_pagination(default_page_size=5, max_page_size=500)),
]
@app.get("/heroes", response_model=Page[HeroModel])
async def get_heroes(paginate: CustomPaginate):
return await paginate(select(Hero))
```
- Session lifecycle management: session is commited on request success or rollback on failure.
- [`SQLModel`](http://sqlmodel.tiangolo.com/) support:
```
...
from fastsqla import Item, Page, Paginate, Session
from sqlmodel import Field, SQLModel
...
class Hero(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
name: str
secret_identity: str
age: int
@app.get("/heroes", response_model=Page[Hero])
async def get_heroes(paginate: Paginate):
return await paginate(select(Hero))
@app.get("/heroes/{hero_id}", response_model=Item[Hero])
async def get_hero(session: Session, hero_id: int):
hero = await session.get(Hero, hero_id)
if hero is None:
raise HTTPException(status_code=HTTPStatus.NOT_FOUND)
return {"data": hero}
```
## Installing
Using [uv](https://docs.astral.sh/uv/):
```
uv add fastsqla
```
Using [pip](https://pip.pypa.io/):
```
pip install fastsqla
```
## Quick Example
### `example.py`
Let's write some tiny app in `example.py`:
```
# example.py
from http import HTTPStatus
from fastapi import FastAPI, HTTPException
from fastsqla import Base, Item, Page, Paginate, Session, lifespan
from pydantic import BaseModel, ConfigDict
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Mapped, mapped_column
app = FastAPI(lifespan=lifespan)
class Hero(Base):
__tablename__ = "hero"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(unique=True)
secret_identity: Mapped[str]
age: Mapped[int]
class HeroBase(BaseModel):
name: str
secret_identity: str
age: int
class HeroModel(HeroBase):
model_config = ConfigDict(from_attributes=True)
id: int
@app.get("/heros", response_model=Page[HeroModel])
async def list_heros(paginate: Paginate):
stmt = select(Hero)
return await paginate(stmt)
@app.get("/heros/{hero_id}", response_model=Item[HeroModel])
async def get_hero(hero_id: int, session: Session):
hero = await session.get(Hero, hero_id)
if hero is None:
raise HTTPException(HTTPStatus.NOT_FOUND, "Hero not found")
return {"data": hero}
@app.post("/heros", response_model=Item[HeroModel])
async def create_hero(new_hero: HeroBase, session: Session):
hero = Hero(**new_hero.model_dump())
session.add(hero)
try:
await session.flush()
except IntegrityError:
raise HTTPException(HTTPStatus.CONFLICT, "Duplicate hero name")
return {"data": hero}
```
### Database
💡 This example uses an `SQLite` database for simplicity: `FastSQLA` is compatible with all asynchronous db drivers that `SQLAlchemy` is compatible with.
Let's create an `SQLite` database using `sqlite3` and insert 12 rows in the `hero` table:
```
sqlite3 db.sqlite <.
## License
This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).
## For coding agents and LLMs
FastSQLA publishes agent-readable documentation alongside the website:
- [`llms.txt`](https://hadrien.github.io/FastSQLA/llms.txt) is the concise documentation index.
- [`llms-full.txt`](https://hadrien.github.io/FastSQLA/llms-full.txt) contains the complete documentation in one file.
- Every indexed page has a Markdown twin, such as [`setup/index.md`](https://hadrien.github.io/FastSQLA/setup/index.md).
- [Context7](https://context7.com/hadrien/fastsqla) serves the current documentation and FastSQLA-specific usage rules.
The repository also bundles Agent Skills for setup, session management, and pagination. Install all three as one plugin:
### Claude Code
```
claude plugin marketplace add hadrien/FastSQLA
claude plugin install fastsqla@fastsqla
```
### Codex
```
codex plugin marketplace add hadrien/FastSQLA
codex plugin add fastsqla@fastsqla
```