什么是 SQLModel？

SQLModel 是一个用于 Python 的数据库交互库，由 FastAPI 的作者 Sebastián Ramírez（@tiangolo）开发。它结合了 SQLAlchemy 的强大数据库操作能力和 Pydantic 的数据验证与序列化功能，旨在提供简洁、类型安全且高效的数据库操作体验。SQLModel 的设计目标是减少代码重复，提升开发者体验，同时保持与 FastAPI、SQLAlchemy 和 Pydantic 的高度兼容性。

• 项目地址：https://github.com/fastapi/sqlmodel
• 文档：https://sqlmodel.tiangolo.com
• 许可证：MIT 许可证
• 当前热度：截至 2025 年 8 月，GitHub 上有 16.6k 星和 754 次 Fork，社区活跃度高。

核心特性

SQLModel 的设计理念是“简单、兼容、强大”，以下是其主要特性：

1. 直观易用：通过 Python 类型注解定义数据库模型，代码简洁，支持编辑器自动补全和类型检查，减少调试时间。
2. 兼容性强：同时支持 SQLAlchemy 和 Pydantic 的功能，既是 SQLAlchemy 模型，也是 Pydantic 模型，方便与 FastAPI 集成。
3. 代码精简：通过单一模型定义同时处理数据库操作和 API 数据验证，极大减少代码重复。
4. 强大的编辑器支持：得益于类型注解，SQLModel 提供出色的自动补全和错误提示，提升开发效率。
5. 异步支持：与 SQLAlchemy 2.0 和异步数据库驱动（如 asyncpg）兼容，适合高性能异步应用。
6. 扩展性：继承 SQLAlchemy 和 Pydantic 的全部功能，开发者可以轻松扩展复杂需求。

为什么选择 SQLModel？

SQLModel 特别适合以下场景：

• FastAPI 项目：SQLModel 与 FastAPI 无缝集成，简化 API 开发中的数据验证和数据库操作。
• 需要类型安全的项目：通过 Pydantic 的数据验证和 Python 类型注解，确保代码健壮性。
• 从 SQLAlchemy 迁移：已有 SQLAlchemy 项目可以平滑过渡到 SQLModel，同时享受更简洁的语法。
• 快速原型开发：SQLModel 的简洁语法和默认配置让开发者能快速构建数据库驱动的应用。

快速上手示例

以下是一个简单的 SQLModel 示例，展示如何定义模型、操作数据库并与 FastAPI 结合：

定义模型

from sqlmodel import Field, SQLModel, create_engine, Session, selectclass Hero(SQLModel, table=True):    id: int | None = Field(default=None, primary_key=True)    name: str    secret_name: str    age: int | None = None

这个 Hero 类既是 SQLAlchemy 的数据库模型（table=True），也是 Pydantic 的数据验证模型。

写入数据库

engine = create_engine("sqlite:///database.db")SQLModel.metadata.create_all(engine)hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)with Session(engine) as session:    session.add(hero_1)    session.add(hero_2)    session.add(hero_3)    session.commit()

查询数据库

with Session(engine) as session:    statement = select(Hero).where(Hero.name == "Spider-Boy")    hero = session.exec(statement).first()    print(hero)  # 输出: Hero(id=2, name='Spider-Boy', secret_name='Pedro Parqueador', age=None)

与 FastAPI 集成

from fastapi import FastAPIfrom sqlmodel import selectapp = FastAPI()@app.get("/heroes/{name}")def get_hero(name: str):    with Session(engine) as session:        statement = select(Hero).where(Hero.name == name)        hero = session.exec(statement).first()        return hero

运行后，访问 http://localhost:8000/heroes/Spider-Boy 即可获取对应英雄的数据，自动享受 FastAPI 的 OpenAPI 文档和 Pydantic 的数据验证。

社区与生态

SQLModel 不仅是一个独立的库，还与 FastAPI 生态紧密相关。以下是一些相关的社区项目：

• FastAPI + SQLModel 模板：如 anthonycepeda/fastapi-sqlmodel 提供完整的项目样板，包含 Docker 和测试配置。
• 用户认证：fastapi-users/fastapi-users-db-sqlmodel 提供了基于 SQLModel 的用户认证模块。
• 异步支持：如 jonra1993/fastapi-alembic-sqlmodel-async，展示如何结合异步 SQLModel 和 Alembic 迁移。