asyncpg.Pool关闭必须await close()和wait_closed()成对调用,缺一不可;生产环境需用asyncio.wait_for(wait_closed(), timeout=5)防卡死,且须在FastAPI lifespan shutdown等异步上下文中执行。

必须显式关闭,且顺序、时机、超时都要控制好,否则连接泄漏是常态,不是例外。
asyncpg.Pool 关闭必须 await close() + wait_closed()
asyncpg 的 Pool 不会在垃圾回收时自动释放连接,只调用 pool.close() 是无效的——它只是发起关闭流程,底层 TCP 连接仍可能存活。真正释放必须跟上 await pool.wait_closed()。
- 常见错误:
await pool.close()后直接退出,导致连接堆积、too many clients already报错 - 生产环境建议用
asyncio.wait_for(pool.wait_closed(), timeout=5)包裹,防止单个慢响应拖住整个 shutdown 流程 - FastAPI 中应在 lifespan 的
shutdown事件里触发;aiohttp 则放在on_cleanup回调中
SQLAlchemy AsyncEngine 的 dispose() 不是 dispose_async()
SQLAlchemy 1.4+ 和 2.0 的 AsyncEngine 没有 dispose_async() 方法——这是社区误传最广的坑。正确方法是 await engine.dispose(),它会清理空闲连接并等待活跃连接归还。
- 错误写法:
await engine.dispose_async()→ 抛AttributeError: 'AsyncEngine' object has no attribute 'dispose_async' -
engine.dispose()不会强制中断正在执行的AsyncSession,所以务必确保 session 已提交/回滚并退出上下文 - URL 必须为
postgresql+asyncpg://,不能混用psycopg或pg8000的异步变体
多个池共存时,关闭顺序必须逆依赖
当项目同时使用主库池、从库读池、审计日志专用池时,关闭顺序直接影响稳定性。如果日志池先关,而主业务池在关闭过程中还要写审计记录,就会触发 ConnectionResetError 或 InterfaceError: connection is closed。
立即学习“Python免费学习笔记(深入)”;
- 安全原则:被其他模块依赖的池(如监控上报、审计写入)最后关
- 典型顺序:主业务池 → 读从库池 → 日志/指标池
- 建议用
try/except包裹每个wait_closed(),避免一个池异常导致后续池无法关闭
连接池参数配置不匹配数据库超时,会导致 silent fail
连接池认为连接“健康”,但数据库已主动断开,结果第一次查询就报 server closed the connection unexpectedly。根本原因是池的 idle 超时与数据库 wait_timeout(MySQL)或 tcp_keepalives_idle(PostgreSQL)不一致。
- 实操底线:池的空闲回收时间(如
min_size/max_size配合pool_recycle)应比数据库侧超时少 10–15 秒 - PostgreSQL 推荐启用 OS 层 keepalive:
tcp_keepalives_idle=60,比应用层 ping 更轻量 - 避免滥用
pool_pre_ping=True:高频预检会增加延迟,仅在低频关键路径启用即可
最容易被忽略的是:所有关闭逻辑都依赖事件循环仍在运行。如果在 asyncio.run() 外部、或线程中直接调用 await,会报 RuntimeError: no running event loop——这意味着你得把 shutdown 步骤嵌进 async 上下文,而不是当成普通函数调用。


















