SQLModel：一个模型，同时搞定 ORM 和数据校验

sqlmodel 在 GitHub 上已经有 18,000 Star。

FastAPI 作者做的 ORM 库，核心思路很简单：用一份代码同时满足 SQLAlchemy 的表映射和 Pydantic 的数据校验，不用写两套模型。

1、这玩意儿是干嘛的

SQLModel 是一个基于 Python 类型注解的 ORM 库，底层由 Pydantic 和 SQLAlchemy 驱动。

它并不替代这两者，定位是把 Pydantic 和 SQLAlchemy 捏合在一起。你写一个类，它同时是 SQLAlchemy 模型，也是 Pydantic 模型。

这意味着什么？以前你要定义一套 SQLAlchemy 模型给数据库用，再定义一套 Pydantic 模型给接口传参和返回值用。SQLModel 把这两件事合到一块，一个类就搞定。

SQLModel 跟 FastAPI、Pydantic、SQLAlchemy 都是兼容的。你已有的 SQLAlchemy 代码可以直接混用，Pydantic 的校验逻辑也全部保留。它只是一个很薄的中间层，没有引入新的抽象概念。

2、为什么要用它

代码重复是多数 Python Web 项目的通病。模型层写两遍，改字段要改两处，一不小心就不同步。

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 做请求体校验和响应序列化。

3、用起来长什么样

创建记录就是实例化对象：

hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")

写入数据库：

from sqlmodel import Session, create_engine

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

with Session(engine) as session:
    session.add(hero_1)
    session.add(hero_2)
    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)

语法跟 SQLAlchemy 2.0 基本一致，没有额外的学习成本。

4、编辑器支持

因为是 Pydantic 模型，IDE 的自动补全和类型检查都能用。SQLModel 官方文档里也着重强调了这一点，写代码时的提示和报错都能正常工作。

5、适合哪些人用

• 在用 FastAPI 开发接口、需要跟数据库打交道的开发者
• 厌倦了维护两套模型、希望减少代码重复的 Python 后端开发者
• 刚开始接触 ORM、想要一个类型友好且文档完整的入门方案的人

安装也很简单：

pip install sqlmodel

Pydantic 和 SQLAlchemy 会自动作为依赖装上。

入门方案的人

安装也很简单：

pip install sqlmodel

Pydantic 和 SQLAlchemy 会自动作为依赖装上。