SQLModel — SQL Databases in Python with Type Safety and Pydantic

Introduction

SQLModel is created by the author of FastAPI and bridges the gap between SQLAlchemy (database operations) and Pydantic (data validation). A single class definition serves as your database table, your API request/response schema, and your editor-friendly type-checked model.

What SQLModel Does

• Defines database tables using Python type annotations
• Provides full SQLAlchemy Core and ORM capabilities underneath
• Validates data at runtime via Pydantic model checks
• Generates editor autocompletion for queries, fields, and relationships
• Integrates seamlessly with FastAPI for request/response models

Architecture Overview

SQLModel classes inherit from both SQLAlchemy's DeclarativeBase and Pydantic's BaseModel. When table=True is set, the class maps to a database table with columns derived from annotated fields. Without table=True, the same class acts as a pure Pydantic schema for validation and serialization.

Self-Hosting & Configuration

• Install via pip; requires Python 3.7+
• Supports SQLite, PostgreSQL, MySQL, and any SQLAlchemy-compatible backend
• Configure the engine with a standard database URL string
• Use Alembic for migrations (SQLModel models are standard SQLAlchemy models)
• Pair with FastAPI's Depends for session management in web apps

Key Features

• Single source of truth for database schema and API schema
• Full type checking and editor autocompletion support
• Relationship declarations with type-safe lazy and eager loading
• Compatible with existing SQLAlchemy code and migrations
• Minimal boilerplate compared to using SQLAlchemy and Pydantic separately

Comparison with Similar Tools

• SQLAlchemy — more powerful and flexible but requires separate Pydantic schemas for API use
• Tortoise ORM — async-first ORM but lacks Pydantic integration
• Peewee — simpler ORM with no type annotation support
• Django ORM — tightly coupled to Django; SQLModel works with any framework
• Prisma (Python client) — code-generated; SQLModel is defined in native Python

FAQ

Q: Can I use SQLModel with an existing SQLAlchemy project? A: Yes. SQLModel models are SQLAlchemy models under the hood. You can mix them in the same engine and session.

Q: Does SQLModel support async operations? A: Yes. Use create_async_engine and AsyncSession from SQLAlchemy's async extensions, which SQLModel supports.

Q: How do I handle migrations? A: Use Alembic. SQLModel tables are standard SQLAlchemy metadata, so Alembic's autogenerate works normally.

Q: Is SQLModel production-ready? A: It is used in production by many teams. The API is considered stable though the version is still below 1.0.

Sources

• https://github.com/tiangolo/sqlmodel
• https://sqlmodel.tiangolo.com