fastapi/sqlmodel

SQL databases in Python, designed for simplicity, compatibility, and robustness.

How Data Flows Through the System

Data enters as Python class definitions with type annotations and Field() declarations. SQLModel's metaclass processes these to generate both Pydantic validation schemas and SQLAlchemy table schemas. At runtime, data flows through Pydantic validation for incoming requests, gets stored via SQLAlchemy sessions, and serializes back through Pydantic for outgoing responses.

1. Model Definition — Developer defines a class inheriting from SQLModel with type-annotated fields and table=True parameter. The SQLModelMetaclass intercepts this class creation to build dual Pydantic/SQLAlchemy schemas.
2. Field Processing — Field() functions are called during class definition, creating FieldInfo objects that contain both Pydantic validation rules and SQLAlchemy column specifications like indexes, foreign keys, and constraints.
3. Table Creation — create_db_and_tables() calls SQLModel.metadata.create_all(engine) to generate actual database tables from the collected SQLAlchemy table metadata of all registered SQLModel classes. [SQLModel]
4. Request Validation — Incoming data (typically JSON from HTTP requests) gets parsed and validated through Pydantic's validation pipeline using the model's type annotations and Field constraints.
5. Database Persistence — Validated model instances are added to SQLAlchemy sessions using session.add(), then persisted to the database with session.commit(), with session.refresh() updating the instance with generated database values like auto-increment IDs. [Hero → Hero]
6. Query Execution — Database queries use the type-safe select() function to build SQLAlchemy queries, executed via session.exec() which returns properly typed result objects that maintain both database and Pydantic model capabilities.
7. Response Serialization — Retrieved database objects are automatically serialized to JSON through Pydantic's serialization, often using dedicated response models like HeroPublic to control which fields are exposed in the API. [Hero → HeroPublic]

Data Models

The data structures that flow between stages — the contracts that hold the system together.

Hidden Assumptions

Things this code relies on but never validates. These are the things that cause silent failures when the system changes.

System Behavior

How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Session Refresh Loop (self-correction, balancing) — Trigger: session.commit() completion. Action: session.refresh() queries database to update object with generated values like auto-increment IDs. Exit: Object synchronized with database state.
• Model Registration Loop (recursive, reinforcing) — Trigger: SQLModel class definition with table=True. Action: Metaclass registers table metadata and updates global registry. Exit: All models processed and registered.

Delays

• Database Connection Pool (async-processing, ~varies by connection availability) — Session creation waits for available database connections from the pool
• Metaclass Processing (compilation, ~class definition time) — Class creation involves building both Pydantic and SQLAlchemy schemas

Control Points

• table Parameter (architecture-switch) — Controls: Whether class becomes database table (table=True) or stays Pydantic-only model (table=False). Default: boolean flag in class definition
• Engine Echo (env-var) — Controls: SQL query logging for debugging - create_engine(echo=True) prints all SQL statements. Default: True
• SQLite Connection Args (runtime-toggle) — Controls: Database connection behavior like thread safety with check_same_thread=False for SQLite. Default: {"check_same_thread": False}

Technology Stack

Key Components

• SQLModel (factory) — Core hybrid class that combines Pydantic model validation with SQLAlchemy ORM table mapping through metaclass inheritance sqlmodel/main.py
• Field (factory) — Enhanced field definition function that creates Pydantic FieldInfo objects extended with SQLAlchemy Column properties like foreign keys and indexes sqlmodel/main.py
• SQLModelMetaclass (orchestrator) — Metaclass that intercepts class creation to build both Pydantic model validation and SQLAlchemy table schema from the same class definition sqlmodel/main.py
• get_session (factory) — FastAPI dependency that creates SQLAlchemy sessions using a context manager pattern for automatic cleanup docs_src/tutorial/fastapi/app_testing/tutorial001_py310/main.py
• create_db_and_tables (orchestrator) — Initializes database schema by calling SQLModel.metadata.create_all() to generate tables from registered model classes docs_src/tutorial/code_structure/tutorial001_py310/database.py
• select (factory) — Query builder function that creates type-safe SQLAlchemy select statements with proper typing for SQLModel classes sqlmodel/sql/expression.py
• Session (gateway) — SQLAlchemy session wrapper that manages database connections and transactions for SQLModel operations sqlmodel/__init__.py

Related Library Repositories

Frequently Asked Questions

Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.