SQLModel

SQLModel is a library for interacting with SQL databases from Python code using Python objects, created by Sebastián Ramírez (tiangolo), the author of FastAPI. It is built directly on top of SQLAlchemy Core and Pydantic, and is designed so that every model class you write is simultaneously a valid SQLAlchemy ORM model and a valid Pydantic model — no more maintaining two parallel sets of classes for your database tables and your API schemas.

Because it inherits full compatibility with both underlying libraries, SQLModel integrates naturally into FastAPI applications: request/response validation, OpenAPI schema generation, and database persistence all read from the same class definition. Developers get editor autocompletion, inline type errors, and a single source of truth for each entity in their application.

What You Get

• A single model class that is simultaneously a SQLAlchemy table definition and a Pydantic schema, removing duplicate class definitions
• Full editor autocompletion and inline type-checking errors powered by standard Python type annotations
• Direct compatibility with existing SQLAlchemy engines, sessions, and migration tools like Alembic
• A select() query builder with the same type-safety guarantees as the rest of the API
• Seamless integration with FastAPI for request/response validation and automatic OpenAPI schema generation
• Support for relationships, foreign keys, and advanced SQLAlchemy column configuration via Field(sa_column=...)

Common Use Cases

• Defining database tables in a FastAPI application without duplicating the model as a separate Pydantic response schema
• Migrating an existing SQLAlchemy-only codebase to gain Pydantic validation for free on the same classes
• Building internal tools and admin scripts that need typed, autocompletable database access
• Rapid prototyping of CRUD APIs where the database schema and the API schema should stay in lockstep

Under The Hood

Architecture: SQLModel’s core (sqlmodel/main.py) defines a SQLModel base class that uses a custom metaclass to merge SQLAlchemy’s DeclarativeMeta with Pydantic’s ModelMetaclass, so a single class body produces both a mapped SQLAlchemy table (when table=True) and a Pydantic model for validation/serialization. Query construction (sqlmodel/sql/expression.py) wraps SQLAlchemy’s select() in a generic-typed subclass so IDEs infer the exact row type returned by session.exec(), and sqlmodel/orm/session.py extends SQLAlchemy’s Session with this typed exec() method as the main entry point for reads.

Tech Stack: The library targets Python 3.10+ and depends on SQLAlchemy 2.0.x and Pydantic 2.11+, using pdm-backend as its build backend and uv for dependency locking (uv.lock). It has no runtime dependencies beyond those two libraries plus typing-extensions, keeping the surface area small and delegating all actual database dialect handling to SQLAlchemy.

Code Quality: The tests/ directory is extensive, with dedicated modules per feature (relationships, enums, defaults, UUIDs, SA column overrides) plus a test_advanced/ suite, and CI runs coverage tracking via a coverage badge service. Code is fully type-annotated (py.typed marker present) and follows consistent naming that mirrors both SQLAlchemy and Pydantic conventions to keep the merged API predictable.

API Design: Getting started requires only a class definition with table=True and type-annotated fields — no separate schema file, no migration boilerplate for a first prototype — and the same class works as a request/response model, database table, and validation schema simultaneously, which is the library’s central ergonomic bet.