SQLModel Integration¶

Advanced Alchemy provides built-in compatibility for SQLModel, allowing you to use SQLModel’s elegant syntax for defining models while leveraging Advanced Alchemy’s powerful repositories and services.

Basic Setup¶

To use SQLModel with Advanced Alchemy, ensure your models are defined with table=True.

Python 3.9+

from typing import Optional
from sqlmodel import Field, SQLModel
from advanced_alchemy.repository import SQLAlchemyAsyncRepository

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: Optional[int] = None

class HeroRepository(SQLAlchemyAsyncRepository[Hero]):
    model_type = Hero

Python 3.10+

from sqlmodel import Field, SQLModel
from advanced_alchemy.repository import SQLAlchemyAsyncRepository

class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None

class HeroRepository(SQLAlchemyAsyncRepository[Hero]):
    model_type = Hero

Usage with Repositories¶

Repositories automatically detect SQLModel classes and handle them correctly during CRUD operations.

from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

async def create_and_list_heroes() -> list[Hero]:
    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
    async_session_factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)

    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.create_all)

    try:
        async with async_session_factory() as session:
            repo = HeroRepository(session=session)

            hero = Hero(name="Deadpond", secret_name="Dive Wilson")
            await repo.add(hero)
            await session.commit()

            return await repo.list()
    finally:
        await engine.dispose()

Limitations¶

While SQLModel is supported, some Advanced Alchemy features that rely on specific SQLAlchemy base class behaviors (like some automated mixin detections) may require explicit configuration when used with SQLModel.