SQLModel：FastAPI 作者写的 ORM，把 Pydantic 和 SQLAlchemy 缝在一起了

SQLModel 在 GitHub 上已经拿到 18K Star 了。

这是 FastAPI 作者 Sebastián Ramírez 搞的又一个项目。它的定位很简单：用 Python 类型注解操作 SQL 数据库，底层同时依赖 Pydantic 和 SQLAlchemy，但上层只暴露一套 API。

1、这玩意儿是干嘛的

做过 Python 后端的人都知道，数据库模型这件事常常要重复写两遍：

SQLAlchemy 定义表结构，Pydantic 定义数据校验模型，两个类除了字段名一样，其他完全不相关。改个字段要改两处，漏了就会出 bug。

SQLModel 把它合并成一个类。你写一个 SQLModel 的子类，它同时是 SQLAlchemy 的表模型，也是 Pydantic 的数据模型。校验、序列化、数据库操作都走同一个定义。

2、实际长什么样

安装就是一行：

pip install sqlmodel

定义一个表：

from sqlmodel import Field, SQLModel

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

这个 Hero 类能直接用来建表、插数据、做查询，也能直接传给 FastAPI 做请求体校验和响应序列化，不需要再写一个 Pydantic schema。

写数据：

from sqlmodel import Session, create_engine

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

hero = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")

with Session(engine) as session:
    session.add(hero)
    session.commit()

查数据：

from sqlmodel import select

with Session(engine) as session:
    statement = select(Hero).where(Hero.name == "Spider-Boy")
    hero = session.exec(statement).first()
    print(hero)

所有操作都是类型化的。IDE 能补全字段名，写错类型会直接报错，调试省不少时间。

3、跟直接用 SQLAlchemy 有什么区别

SQLModel 本质上是 SQLAlchemy 和 Pydantic 的薄封装，不是替代品。SQLAlchemy 能做的复杂查询、关系映射、连接池配置，SQLModel 都能做，因为它底层就是 SQLAlchemy。

差别在于上手门槛和样板代码量。纯 SQLAlchemy 要写 Column、Integer、String 一堆声明式代码，Pydantic v2 又要写一套独立的模型。SQLModel 把这两套通过类型注解统一了，类定义更短，心智负担也更小。

兼容性方面，SQLModel 跟 FastAPI、Pydantic、SQLAlchemy 都能无缝配合，这也是它被设计出来的初衷。

4、适合哪些人用

• 已经在用 FastAPI，想减少一层模型重复定义的人
• 希望 ORM 模型同时能当 API 的 request/response schema 用的人
• 对类型提示和 IDE 补全有要求，不想手写太多样板代码的开发者

如果你在用 Django ORM 或者 Tortoise ORM，迁移过来意义不大。SQLModel 的优势是在 SQLAlchemy 生态里省一层胶水代码，不是替代整个 ORM 层。

ngo ORM 或者 Tortoise ORM，迁移过来意义不大。SQLModel 的优势是在 SQLAlchemy 生态里省一层胶水代码，不是替代整个 ORM 层。