# SQLModel — SQL Databases in Python with Type Safety and Pydantic

> SQLModel combines SQLAlchemy and Pydantic into a single library, letting you define database models as Python classes with type annotations that serve as both ORM models and data validation schemas.

## Install

Save as a script file and run:

# SQLModel — SQL Databases in Python with Type Safety and Pydantic

## Quick Use
```bash
pip install sqlmodel

# main.py
from sqlmodel import Field, SQLModel, Session, create_engine, select

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

engine = create_engine("sqlite:///database.db")
SQLModel.metadata.create_all(engine)

with Session(engine) as session:
    hero = Hero(name="Spider-Boy", secret_name="Pedro")
    session.add(hero)
    session.commit()
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-61fdc9f9
Author: Script Depot