SQLModel

0.0.38 · active · verified Mon Apr 06

SQLModel is a Python library that unifies SQLAlchemy's ORM capabilities with Pydantic's data validation, simplifying interaction with SQL databases. It aims to reduce code duplication by using a single class definition for both database models and data schemas. SQLModel is currently in version 0.0.38 and maintains an active development cadence with frequent releases, often including bug fixes, dependency updates, and sometimes breaking changes.

Warnings

breaking SQLModel versions 0.0.35 and higher require Python 3.10 or later.
Fix: Upgrade your Python environment to 3.10 or newer. For older Python versions, use SQLModel < 0.0.35.
breaking SQLModel version 0.0.31 dropped support for Pydantic v1. It now requires Pydantic v2.
Fix: Upgrade Pydantic to version 2 (e.g., `pip install pydantic==2.*`). Be aware that Pydantic v2 has its own breaking changes. If you must use Pydantic v1, pin SQLModel to `<0.0.31` or use `pydantic<2`.
gotcha SQLModel `Session` objects are not thread-safe and should be created per request/task, typically using a `with Session(engine) as session:` block. Detached objects (queried in one session, then used in another) can lead to unexpected behavior.
Fix: Always use a new `Session` context manager for each logical unit of work. For FastAPI, use `Depends` to inject a session per request. Ensure all operations on a model instance occur within the same session that loaded it.
gotcha For asynchronous database operations, you must use `sqlalchemy.ext.asyncio.create_async_engine` and `sqlalchemy.ext.asyncio.AsyncSession` (or `sqlmodel.ext.asyncio.Session` when available). Also, ensure you use an async-compatible database driver (e.g., `aiosqlite` for SQLite, `asyncpg` for PostgreSQL).
Fix: Install the correct async driver (e.g., `pip install sqlmodel[aiosqlite]`). Use `create_async_engine` with a proper async database URL (e.g., `sqlite+aiosqlite:///./test.db`). Manage async sessions with `async with AsyncSession(engine) as session:`.
gotcha The `SQLModel.metadata.create_all(engine)` call must be executed *after* all your `SQLModel` classes have been defined. If models are in separate files, ensure they are imported before `create_all` is called.
Fix: Structure your code so model definitions are fully loaded before `SQLModel.metadata.create_all()` is invoked. For complex applications, consider using a database migration tool like Alembic.
gotcha When defining relationships between models (e.g., `Hero` and `Team`), circular import issues can arise with type annotations. Python's runtime cannot resolve these.
Fix: Use `from typing import TYPE_CHECKING` and import classes inside an `if TYPE_CHECKING:` block for type-checking tools. For example: `if TYPE_CHECKING: from .other_model import OtherModel`.

Install

pip install sqlmodel Standard Installation
pip install sqlmodel[asyncpg] For PostgreSQL with Async
pip install sqlmodel[aiosqlite] For SQLite with Async

Imports

SQLModel
```
from sqlmodel import SQLModel
```
Field
```
from sqlmodel import Field
```
Session
```
from sqlmodel import Session
```
create_engine
```
from sqlmodel import create_engine
```
select
```
from sqlmodel import select
```
SQLModel's `select` provides enhanced type annotations and automatically handles `.scalars()` which SQLAlchemy's version doesn't.
create_async_engine
```
from sqlalchemy.ext.asyncio import create_async_engine
```
Async engine is imported directly from SQLAlchemy's async extension.
AsyncSession
```
from sqlalchemy.ext.asyncio import AsyncSession
```
Async session is imported directly from SQLAlchemy's async extension.

Quickstart

This quickstart demonstrates how to define a `SQLModel` table, create a database engine (using SQLite in this case), create the database tables, and then insert and query data. It showcases the combined power of Pydantic-like model definition with SQLAlchemy's ORM operations. The `echo=True` in `create_engine` will print SQL statements to the console.

from typing import Optional
from sqlmodel import Field, Session, SQLModel, create_engine, select

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

sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

# Or for in-memory:
# sqlite_url = "sqlite://"

engine = create_engine(sqlite_url, echo=True)

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

def create_heroes():
    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
    hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador", age=16)
    hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)

    with Session(engine) as session:
        session.add(hero_1)
        session.add(hero_2)
        session.add(hero_3)

        session.commit()

        session.refresh(hero_1)
        session.refresh(hero_2)
        session.refresh(hero_3)

        print("Created heroes:", hero_1, hero_2, hero_3)

def select_heroes():
    with Session(engine) as session:
        statement = select(Hero).where(Hero.age >= 18)
        results = session.exec(statement)
        heroes = results.all()
        print("Adult heroes:", heroes)

def main():
    create_db_and_tables()
    create_heroes()
    select_heroes()

if __name__ == "__main__":
    main()

view raw JSON →