FastAPI 接入异步 PostgreSQL 完成任务 CRUD 与数据库迁移

内存列表写起来很轻松，服务一重启，昨天创建的任务就像没发生过。真正麻烦的还不只是丢数据，多个请求同时改一条任务时，列表也没有事务可言。这一篇把第一篇的接口换成 PostgreSQL，并让迁移脚本替我们记录表结构的变化。

配套代码已经放在 fastapi-task-api，文章中的完整实现以 main 分支为准。

让数据库连接成为配置

数据库地址不能散落在路由里。开发机、测试环境和 Docker 容器的主机名都不同，把它收进配置模型，部署时只需要替换环境变量。

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    database_url: str = "postgresql+asyncpg://task_api:task_api@localhost:5432/task_api"
    model_config = SettingsConfigDict(env_file=".env")

项目使用 SQLAlchemy 2 的异步引擎和 asyncpg 驱动。异步不是让每条 SQL 更快，它让等待数据库返回的时间可以让给别的请求。

from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

engine = create_async_engine(settings.database_url, pool_pre_ping=True)
SessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)


async def get_session():
    async with SessionLocal() as session:
        yield session  # 一个请求拿到一个会话

pool_pre_ping=True 会在复用连接前检查连接是否还活着。数据库重启后直接复用旧连接，是线上很常见的一类偶发错误。

模型描述表，Schema 描述接口

ORM 模型和 Pydantic 模型看起来字段相似，职责却不同。前者描述表、外键和索引，后者描述接口允许传入或返回什么。把两者硬合在一个类里，起步很快，后面加密码字段或内部状态时就会开始泄漏。

import uuid
from enum import StrEnum
from sqlalchemy import Enum, ForeignKey, String
from sqlalchemy.orm import Mapped, mapped_column


class TaskStatus(StrEnum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    DONE = "done"


class Task(Base):
    __tablename__ = "tasks"

    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    title: Mapped[str] = mapped_column(String(200))
    status: Mapped[TaskStatus] = mapped_column(Enum(TaskStatus), default=TaskStatus.TODO)
    owner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), index=True)

这里已经预留了 owner_id。第三篇才会引入用户认证，但表结构早点确定，迁移就不会反复推倒重来。

一次查询如何穿过依赖注入

路由不应该自己创建连接。Depends 把会话传进函数，框架在请求结束后关闭它。回到任务列表这块，分页和状态筛选仍然是第一篇的接口，只是实现从切片换成 SQL。

from sqlalchemy import func, select


@router.get("", response_model=TaskList)
async def list_tasks(
    skip: int = Query(0, ge=0),
    limit: int = Query(20, ge=1, le=100),
    task_status: TaskStatus | None = Query(None, alias="status"),
    session: AsyncSession = Depends(get_session),
) -> TaskList:
    condition = Task.owner_id == current_user.id
    if task_status is not None:
        condition = condition & (Task.status == task_status)
    total = await session.scalar(select(func.count()).select_from(Task).where(condition))
    rows = await session.scalars(select(Task).where(condition).offset(skip).limit(limit))
    return TaskList(items=list(rows), total=total or 0)

查询列表和统计总数是两条 SQL，这在多数后台页面足够清楚。数据量很大时再改用游标分页，不要为了一个十条数据的任务清单提前造复杂方案。

迁移不是可有可无的脚本

直接 create_all() 在本地很方便，团队协作就会变得危险。谁在什么时候加了列，没有可追溯记录。Alembic 把每次 schema 变更写成版本文件，发布时按顺序执行。

uv add alembic asyncpg sqlalchemy
uv run alembic revision --autogenerate -m "create users and tasks"
uv run alembic upgrade head

本项目的首个迁移创建 users 和 tasks 两张表，并为邮箱和任务所有者建立索引。自动生成的迁移也要人工审一遍，特别是删除列、枚举变化和大表加索引。工具只知道模型变了，不知道线上数据值不值得保留。
#mermaid-svg-sBFdIDujWJcsAlub{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-sBFdIDujWJcsAlub .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-sBFdIDujWJcsAlub .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-sBFdIDujWJcsAlub .error-icon{fill:#552222;}#mermaid-svg-sBFdIDujWJcsAlub .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-sBFdIDujWJcsAlub .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-sBFdIDujWJcsAlub .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-sBFdIDujWJcsAlub .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-sBFdIDujWJcsAlub .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-sBFdIDujWJcsAlub .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-sBFdIDujWJcsAlub .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-sBFdIDujWJcsAlub .marker{fill:#333333;stroke:#333333;}#mermaid-svg-sBFdIDujWJcsAlub .marker.cross{stroke:#333333;}#mermaid-svg-sBFdIDujWJcsAlub svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-sBFdIDujWJcsAlub p{margin:0;}#mermaid-svg-sBFdIDujWJcsAlub .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-sBFdIDujWJcsAlub .cluster-label text{fill:#333;}#mermaid-svg-sBFdIDujWJcsAlub .cluster-label span{color:#333;}#mermaid-svg-sBFdIDujWJcsAlub .cluster-label span p{background-color:transparent;}#mermaid-svg-sBFdIDujWJcsAlub .label text,#mermaid-svg-sBFdIDujWJcsAlub span{fill:#333;color:#333;}#mermaid-svg-sBFdIDujWJcsAlub .node rect,#mermaid-svg-sBFdIDujWJcsAlub .node circle,#mermaid-svg-sBFdIDujWJcsAlub .node ellipse,#mermaid-svg-sBFdIDujWJcsAlub .node polygon,#mermaid-svg-sBFdIDujWJcsAlub .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-sBFdIDujWJcsAlub .rough-node .label text,#mermaid-svg-sBFdIDujWJcsAlub .node .label text,#mermaid-svg-sBFdIDujWJcsAlub .image-shape .label,#mermaid-svg-sBFdIDujWJcsAlub .icon-shape .label{text-anchor:middle;}#mermaid-svg-sBFdIDujWJcsAlub .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-sBFdIDujWJcsAlub .rough-node .label,#mermaid-svg-sBFdIDujWJcsAlub .node .label,#mermaid-svg-sBFdIDujWJcsAlub .image-shape .label,#mermaid-svg-sBFdIDujWJcsAlub .icon-shape .label{text-align:center;}#mermaid-svg-sBFdIDujWJcsAlub .node.clickable{cursor:pointer;}#mermaid-svg-sBFdIDujWJcsAlub .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-sBFdIDujWJcsAlub .arrowheadPath{fill:#333333;}#mermaid-svg-sBFdIDujWJcsAlub .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-sBFdIDujWJcsAlub .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-sBFdIDujWJcsAlub .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sBFdIDujWJcsAlub .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-sBFdIDujWJcsAlub .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sBFdIDujWJcsAlub .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-sBFdIDujWJcsAlub .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-sBFdIDujWJcsAlub .cluster text{fill:#333;}#mermaid-svg-sBFdIDujWJcsAlub .cluster span{color:#333;}#mermaid-svg-sBFdIDujWJcsAlub div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-sBFdIDujWJcsAlub .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-sBFdIDujWJcsAlub rect.text{fill:none;stroke-width:0;}#mermaid-svg-sBFdIDujWJcsAlub .icon-shape,#mermaid-svg-sBFdIDujWJcsAlub .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sBFdIDujWJcsAlub .icon-shape p,#mermaid-svg-sBFdIDujWJcsAlub .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-sBFdIDujWJcsAlub .icon-shape .label rect,#mermaid-svg-sBFdIDujWJcsAlub .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sBFdIDujWJcsAlub .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-sBFdIDujWJcsAlub .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-sBFdIDujWJcsAlub :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 修改 ORM 模型
生成迁移
检查 SQL
提交版本库
部署执行 upgrade

常见卡点

await 少写一个，SQLAlchemy 往往不会立刻报出最直观的错误。session.execute、session.commit、session.refresh 都是异步边界。另一个坑是把 ORM 对象原样返回，建议在响应模型上开启 from_attributes=True，由 Pydantic 只挑选公开字段。

还有一点经常被忽略，commit 后数据库生成的 id 和时间戳不会自动回到 Python 对象。创建接口里要 await session.refresh(task)，否则响应有机会缺字段。

数据库接入完成后，任务终于能活过一次重启。但谁能读和改哪条任务，还没有答案。

下一篇把 owner_id 接到真实用户上，再用测试把这些规则固定下来。

本篇收口

• 异步会话通过依赖注入按请求创建和释放
• ORM 管表结构，Pydantic 管接口边界
• 列表查询同时返回数据和总数，支持分页与状态筛选
• Alembic 让 schema 变化有版本、可审查、可部署