FastAPI 接入数据库时,需要先区分 Session 的生命周期和事务的生命周期:
Engine、连接池和 Session 工厂按应用进程复用;每个请求或任务创建独立 AsyncSession;每个完整业务动作拥有数据库事务边界。Session 生命周期和事务生命周期不同,不能把全局 Engine 的复用误解为共享 Session。
APPLICATION
REQUEST / TASK
BUSINESS ACTION
Engine / Pool / 工厂
应用级复用
AsyncSession
每次请求或任务独立
数据库事务
覆盖完整业务动作
把这三层放进一次真实请求中,执行顺序会更直观:
HTTP 请求进入后,FastAPI 创建请求级 AsyncSession,路由校验参数并调用 Service。Service 开启事务,Repository 执行 SQL 并 flush,事务提交或回滚,路由在关闭 Session 前转换为 Pydantic 响应对象,最后 FastAPI 关闭 Session。
FLOW / RELATIONSHIP
HTTP 请求
创建 AsyncSession
本次请求独立使用
Route
校验参数、调用 Service
Service
开启业务事务
Repository
执行 SQL、flush 获取生成值
结束事务
提交或回滚
转换响应
ORM → Pydantic
关闭 AsyncSession
FastAPI 完成清理
Engine 不是“一条始终打开的数据库连接”,而是连接池及连接获取逻辑的入口。AsyncSession 通常在第一次执行 SQL 时才从连接池取得连接,事务结束后再把连接归还给连接池。因此,应用可以共享 Engine,请求之间却不能共享 Session。
Engine
Engine 应在应用进程中复用。如果每次请求都创建 Engine,就会同时创建很多连接池,失去复用连接的意义。使用多个 worker 时,每个进程都有自己的 Engine 和连接池,因此还要结合 worker 数量规划 PostgreSQL 的总连接上限。
1from sqlalchemy.ext.asyncio import create_async_engine 2 3from app.core.settings import settings 4 5 6engine = create_async_engine( 7 settings.database_url, 8 pool_pre_ping=True, 9)
pool_pre_ping=True 会在从连接池取出连接时检查它是否仍然可用,能够减少数据库重启或网络中断后拿到失效连接的情况,但也会增加一次连接检查。是否设置连接池大小、溢出数量和等待超时,应根据部署进程数与数据库容量决定。
pool_pre_ping=True
Session 工厂同样可以全局复用,但它创建出来的 Session 不能全局共享:
01from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker 02 03from app.db.engine import engine 04 05 06session_factory = async_sessionmaker( 07 engine, 08 class_=AsyncSession, 09 expire_on_commit=False, 10)
应用关闭时应释放 Engine 持有的连接。使用 FastAPI lifespan:
01from collections.abc import AsyncIterator 02from contextlib import asynccontextmanager 03 04from fastapi import FastAPI 05 06from app.db.engine import engine 07 08 09@asynccontextmanager 10async def lifespan(_app: FastAPI) -> AsyncIterator[None]: 11 try: 12 yield 13 finally: 14 await engine.dispose() 15 16 17app = FastAPI(lifespan=lifespan)
try/finally 保证应用退出或 lifespan 内部出现异常时都会释放 Engine 持有的连接。这里没有调用 Base.metadata.create_all(),数据库结构由部署阶段的 Alembic 迁移准备,应用启动只负责使用现有结构。
try/finally
Base.metadata.create_all()
FastAPI 的 yield 依赖适合管理一次请求的 Session 生命周期:
yield
01from collections.abc import AsyncIterator 02from typing import Annotated 03 04from fastapi import Depends 05from sqlalchemy.ext.asyncio import AsyncSession 06 07from app.db.session import session_factory 08 09 10async def get_db_session() -> AsyncIterator[AsyncSession]: 11 async with session_factory() as session: 12 try: 13 yield session 14 except Exception: 15 await session.rollback() 16 raise 17 18 19DbSession = Annotated[ 20 AsyncSession, 21 Depends(get_db_session, scope="function"), 22]
请求进入路径函数前会创建 Session,路由和服务共用它。scope 只对包含 yield 的依赖有意义。这里把依赖范围设为 scope="function",因此路径函数执行完成后、响应发送前就会运行 yield 后的清理代码,Session 随即关闭,连接也会归还给连接池。
scope
scope="function"
这种设置有一个重要前提:路由必须在返回前把 ORM 对象转换成已经包含响应数据的 Pydantic 对象,不能在 Session 关闭后再触发关系加载。流式接口应优先在开始发送响应前读取完所需数据;如果生成器确实要在发送期间继续查询数据库,则需要让 Session 覆盖完整的流式响应生命周期,并控制持续时间,否则慢客户端会长期占用 Session 和连接。
依赖不会自动提交。事务边界由掌握完整业务动作的服务控制,这样一个业务动作可以调用多个仓库方法,最后一起提交或回滚。异常路径中的显式 rollback() 是一道兜底;Session 关闭时也会结束尚未完成的事务,但显式回滚能让异常处理的意图更清楚。只读查询产生的隐式事务会在 Session 关闭时结束。
rollback()
同一个请求中的顺序调用可以共享 Session,但不能把同一个 AsyncSession 同时传入多个 asyncio 并发任务。每个并发任务都需要自己的 Session 和事务。
asyncio
DbSession 把类型和依赖声明组合起来,路由参数只需要写一个清楚的类型名。它与前面 FastAPI 依赖篇介绍的 Annotated 是同一种用法。
DbSession
Annotated
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 连接资源
FastAPI 接入数据库时,需要先区分 Session 的生命周期和事务的生命周期:
Engine、连接池和 Session 工厂按应用进程复用;每个请求或任务创建独立 AsyncSession;每个完整业务动作拥有数据库事务边界。Session 生命周期和事务生命周期不同,不能把全局 Engine 的复用误解为共享 Session。
APPLICATION
REQUEST / TASK
BUSINESS ACTION
Engine / Pool / 工厂
应用级复用
AsyncSession
每次请求或任务独立
数据库事务
覆盖完整业务动作
把这三层放进一次真实请求中,执行顺序会更直观:
HTTP 请求进入后,FastAPI 创建请求级 AsyncSession,路由校验参数并调用 Service。Service 开启事务,Repository 执行 SQL 并 flush,事务提交或回滚,路由在关闭 Session 前转换为 Pydantic 响应对象,最后 FastAPI 关闭 Session。
FLOW / RELATIONSHIP
HTTP 请求
创建 AsyncSession
本次请求独立使用
Route
校验参数、调用 Service
Service
开启业务事务
Repository
执行 SQL、flush 获取生成值
结束事务
提交或回滚
转换响应
ORM → Pydantic
关闭 AsyncSession
FastAPI 完成清理
Engine不是“一条始终打开的数据库连接”,而是连接池及连接获取逻辑的入口。AsyncSession通常在第一次执行 SQL 时才从连接池取得连接,事务结束后再把连接归还给连接池。因此,应用可以共享 Engine,请求之间却不能共享 Session。Engine 应在应用进程中复用。如果每次请求都创建 Engine,就会同时创建很多连接池,失去复用连接的意义。使用多个 worker 时,每个进程都有自己的 Engine 和连接池,因此还要结合 worker 数量规划 PostgreSQL 的总连接上限。
pool_pre_ping=True会在从连接池取出连接时检查它是否仍然可用,能够减少数据库重启或网络中断后拿到失效连接的情况,但也会增加一次连接检查。是否设置连接池大小、溢出数量和等待超时,应根据部署进程数与数据库容量决定。Session 工厂同样可以全局复用,但它创建出来的 Session 不能全局共享:
应用关闭时应释放 Engine 持有的连接。使用 FastAPI lifespan:
try/finally保证应用退出或 lifespan 内部出现异常时都会释放 Engine 持有的连接。这里没有调用Base.metadata.create_all(),数据库结构由部署阶段的 Alembic 迁移准备,应用启动只负责使用现有结构。Session 依赖
FastAPI 的
yield依赖适合管理一次请求的 Session 生命周期:请求进入路径函数前会创建 Session,路由和服务共用它。
scope只对包含yield的依赖有意义。这里把依赖范围设为scope="function",因此路径函数执行完成后、响应发送前就会运行yield后的清理代码,Session 随即关闭,连接也会归还给连接池。这种设置有一个重要前提:路由必须在返回前把 ORM 对象转换成已经包含响应数据的 Pydantic 对象,不能在 Session 关闭后再触发关系加载。流式接口应优先在开始发送响应前读取完所需数据;如果生成器确实要在发送期间继续查询数据库,则需要让 Session 覆盖完整的流式响应生命周期,并控制持续时间,否则慢客户端会长期占用 Session 和连接。
依赖不会自动提交。事务边界由掌握完整业务动作的服务控制,这样一个业务动作可以调用多个仓库方法,最后一起提交或回滚。异常路径中的显式
rollback()是一道兜底;Session 关闭时也会结束尚未完成的事务,但显式回滚能让异常处理的意图更清楚。只读查询产生的隐式事务会在 Session 关闭时结束。同一个请求中的顺序调用可以共享 Session,但不能把同一个
AsyncSession同时传入多个asyncio并发任务。每个并发任务都需要自己的 Session 和事务。DbSession把类型和依赖声明组合起来,路由参数只需要写一个清楚的类型名。它与前面 FastAPI 依赖篇介绍的Annotated是同一种用法。