您如何将 SQL 数据库与 FastAPI 集成？

Question

Accepted Answer

与 Django 不同，FastAPI 对数据库是 **unopinionated**（无固定偏见）的 — 您可以选择库。常见的选择是 **SQLAlchemy**（通常与 **SQLModel** 一起使用，SQLModel 由 FastAPI 作者开发，结合了 SQLAlchemy + Pydantic）。数据库会话通过依赖注入提供。

## SQLAlchemy setup

```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

engine = create_engine("postgresql://user:pass@localhost/db")
SessionLocal = sessionmaker(bind=engine)
Base = declarative_base()

class User(Base):                        # an ORM model (maps to a table)
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
```

## 通过依赖提供 DB 会话

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                 # provide the session
    finally:
        db.close()               # ALWAYS close after the request (cleanup)

@app.get("/users/{id}")
def get_user(id: int, db: Session = Depends(get_db)):   # inject a session per request
    user = db.query(User).filter(User.id == id).first()
    if not user:
        raise HTTPException(404, "Not found")
    return user
```

`yield` 依赖模式是管理会话的标准方式：每个请求打开一个，注入它，然后自动关闭 — 每个端点都获得一个干净且正确关闭的会话。

## SQLModel — SQLAlchemy + Pydantic 合一

```python
from sqlmodel import SQLModel, Field, Session, select

class User(SQLModel, table=True):        # ONE class = ORM model AND Pydantic model
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str

@app.get("/users")
def list_users(db: Session = Depends(get_session)):
    return db.exec(select(User)).all()    # query; results are also valid response models
```

SQLModel 将 ORM 模型和 Pydantic 模型统一为一个类 — 减少数据库和 API schema 之间的重复。

## 迁移和异步选项

```text
✓ Migrations: use Alembic (SQLAlchemy's migration tool) for schema changes
✓ Async: use SQLAlchemy's async engine + async session for async endpoints
  (don't use a SYNC database driver inside async def — it blocks the event loop)
```

## 为什么这很重要

数据库集成对几乎任何真实 API 都是必需的，由于 FastAPI 刻意对此持 **unopinionated**（无固定偏见）态度（不同于 Django 的内置 ORM），理解常见的方法是重要的实践知识。

标准模式 — **SQLAlchemy**（或 **SQLModel**，它巧妙地统一 ORM 和 Pydantic 模型以减少重复）与通过 `yield` 模式的 **依赖注入会话** — 是几乎每个 FastAPI 应用用来持久化数据的方式。

会话-每-请求依赖（打开前、关闭后、自动完成）是管理数据库连接的习惯用语和正确方式，SQLModel 对数据库和 API schema 的统一是来自 FastAPI 作者本人的一项显著的生产力特性。

了解如何设置数据库、通过 DI 提供会话、执行查询、处理迁移（Alembic）和异步注意事项（在异步端点中使用异步驱动程序，永远不要阻塞同步端点）对构建数据驱动的 FastAPI 应用是必需的 — 由于 FastAPI 给您选择的自由，了解常规的、久经考验的路径对正确构建真实应用是有价值的。