FastAPI应用关闭时如何优雅释放数据库连接？

Question

当FastAPI应用部署在ASGI服务器（如Uvicorn）中时，如何在应用关闭时优雅释放数据库连接成为一个关键问题。常见场景是：应用使用SQLAlchemy异步引擎与PostgreSQL/MySQL等数据库保持长连接，但在服务终止时未正确关闭连接池，导致出现“连接泄露”或“Too many connections”错误。由于FastAPI依赖Starlette的生命周期事件，开发者常误用`@app.on_event("shutdown")`来清理资源，但该事件在多进程或多工作进程模式下可能不被触发。因此，如何确保在Uvicorn主进程退出前正确调用数据库连接的`dispose()`或`close()`方法，成为保障系统稳定性的技术难点。

Answer 1

FastAPI 应用在 ASGI 服务器中优雅关闭数据库连接的深度解析

1. 背景与问题引入

在现代微服务架构中，FastAPI 因其高性能和异步支持成为主流选择。当部署在 Uvicorn 等 ASGI 服务器上时，应用通常使用 SQLAlchemy 的异步引擎（AsyncEngine）与 PostgreSQL 或 MySQL 建立长连接以提升性能。然而，在服务终止过程中，若未正确释放数据库连接池资源，极易引发“Too many connections”错误或连接泄露。

开发者常依赖 @app.on_event("shutdown") 来执行清理逻辑，例如调用 engine.dispose()。但该方法存在严重缺陷：在多工作进程（如 Uvicorn 使用 --workers 启动多个 worker 进程）模式下，每个 worker 拥有独立的应用实例，而主进程并不运行 ASGI 应用上下文，导致 shutdown 事件无法被可靠触发。

2. 核心机制分析

Starlette（FastAPI 的底层框架）定义了两种生命周期事件：

• startup：应用启动时触发，用于初始化资源（如数据库引擎）
• shutdown：应用关闭前触发，用于释放资源

这些事件通过 ASGI 协议的 lifespan 协议实现，仅在单进程模式下有效。一旦启用多 worker 模式（生产环境常见），每个 worker 是独立的 Python 进程，彼此隔离，主进程不参与请求处理，因此也不会执行任何 FastAPI 定义的 shutdown 回调。

3. 常见误用场景与后果

场景	代码示例	风险等级	典型表现
单 worker + on_event(shutdown)	@app.on_event("shutdown") async def shutdown_db(): await engine.dispose()	低	可正常释放连接
多 worker + on_event(shutdown)	同上	高	部分连接未释放，连接数持续增长
信号捕获缺失	无全局信号监听	高	进程被 kill -9 后连接滞留数据库端
未使用连接池超时配置	pool_timeout=0, pool_pre_ping=False	中	死连接堆积

4. 解决方案演进路径

为解决上述问题，需从单一应用层事件扩展至进程级资源管理。以下是三种递进式解决方案：

4.1 方案一：使用 Lifespan Context Manager（推荐用于开发/单 worker）

利用 FastAPI 新版本推荐的 lifespan 上下文管理器替代已弃用的 on_event：

from contextlib import asynccontextmanager
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine("postgresql+asyncpg://...")

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    await engine.dispose()  # 确保关闭连接池

app = FastAPI(lifespan=lifespan)
    

4.2 方案二：注册操作系统信号处理器（适用于多 worker 生产环境）

在每个 worker 进程中注册信号处理器，确保 SIGTERM/SIGINT 被捕获并执行清理：

import signal
import asyncio
from uvicorn import Config, Server

def setup_signal_handlers(engine):
    def handle_sig(signum, frame):
        print(f"Received signal {signum}, shutting down...")
        loop = asyncio.get_event_loop()
        loop.create_task(shutdown_engine(engine))

    async def shutdown_engine(engine):
        print("Disposing database engine...")
        await engine.dispose()

    signal.signal(signal.SIGTERM, handle_sig)
    signal.signal(signal.SIGINT, handle_sig)

# 在每个 worker 启动时调用
setup_signal_handlers(engine)
    

4.3 方案三：结合 Gunicorn + Uvicorn Worker 的 Hook 机制（最佳实践）

当使用 Gunicorn 管理多个 Uvicorn worker 时，可通过 gunicorn.conf.py 配置 pre-fork 和 post-worker-init 钩子：

# gunicorn.conf.py
def when_ready(server):
    print("Server is ready. Starting workers...")

def post_worker_init(worker):
    from app.db import engine  # 延迟导入避免共享状态
    worker.log.info("Worker spawned (pid: %s)", worker.pid)
    
    # 为每个 worker 注册 shutdown hook
    import asyncio
    loop = asyncio.get_event_loop()
    loop.add_signal_handler(
        getattr(signal, 'SIGTERM', 15),
        lambda: loop.create_task(shutdown_db(engine))
    )

async def shutdown_db(engine):
    print("Closing DB connection for worker...")
    await engine.dispose()
    

5. 架构设计建议与监控策略

为保障系统长期稳定运行，应结合以下设计原则：

1. 始终设置合理的连接池参数，如 pool_size, max_overflow, pool_timeout
2. 启用 pool_pre_ping=True 防止死连接
3. 在数据库侧设置连接超时（如 PostgreSQL 的 idle_in_transaction_session_timeout）
4. 使用 Prometheus + Grafana 监控活跃连接数趋势
5. 定期审计日志中的 “closing connection” 和 “too many clients” 错误
6. 在 Kubernetes 中配置优雅终止周期（graceful termination period）
7. 避免在模块顶层直接创建 engine，应通过依赖注入容器管理生命周期
8. 对关键服务添加健康检查接口，包含数据库连接状态探测
9. 使用 atexit 作为最后兜底机制（尽管在异步环境中有限制）
10. 考虑使用连接代理（如 PgBouncer）解耦应用与数据库直连

6. 流程图：优雅关闭全流程控制

graph TD
            A[收到 SIGTERM] --> B{是否为 Uvicorn 主进程?}
            B -- 是 --> C[无需操作, 由 Gunicorn 管理]
            B -- 否 --> D[进入 Worker Shutdown 流程]
            D --> E[调用 signal handler]
            E --> F[获取当前 AsyncEngine 实例]
            F --> G[await engine.dispose()]
            G --> H[等待所有连接归还池并关闭]
            H --> I[退出进程]
            I --> J[系统回收资源]