默认配置撑不住高并发，因pool_size=5、max_overflow=10，仅支持15并发连接，超量请求阻塞在pool_timeout=30秒导致超时或timeouterror。
SQLAlchemy连接池默认配置为什么撑不住高并发？
默认的 create_engine 不显式配置池参数时，会启用 QueuePool，但 pool_size=5、max_overflow=10，意味着最多只有 15 个并发连接可用。一旦请求量持续超过这个数，后续请求就会阻塞在获取连接这一步，表现为查询延迟陡增、甚至超时——你看到的 TimeoutError: QueuePool limit of size 5 overflow 10 reached 就是典型信号。
这不是数据库扛不住，而是 SQLAlchemy 在应用层就把连接卡死了。
-
pool_size是常驻连接数，设太小会导致频繁创建/销毁连接（开销大）；设太大则可能耗尽数据库最大连接数（如 PostgreSQL 默认max_connections=100） -
max_overflow是临时弹性扩容上限，只在高峰瞬时起作用，用完即丢，但会加剧连接抖动 -
pool_timeout默认 30 秒，线上服务通常应压到 2–5 秒，避免线程长时间挂起
怎么配出适合 Web API 的连接池参数？
关键不是堆数字，而是匹配你的部署模型：比如用 Gunicorn 启 4 个工作进程、每个进程用 20 个线程（或 asyncio + asyncpg），那理论最大连接需求 ≈ 4 × 20 = 80。但必须留余量，并和数据库侧限制对齐。
推荐起始配置（PostgreSQL 场景）：
from sqlalchemy import create_engine
engine = create_engine(
"postgresql+psycopg2://user:pass@localhost/db",
pool_size=20,
max_overflow=30,
pool_timeout=3,
pool_recycle=3600,
pool_pre_ping=True,
)
-
pool_size=20：保证多数请求能立刻拿到空闲连接，避免排队 -
max_overflow=30：允许短时脉冲到 50 连接，之后新请求开始等待或超时 -
pool_recycle=3600：强制每小时重连一次，防止数据库因闲置连接超时（tcp_keepalive或idle_in_transaction_session_timeout）主动断连导致的OperationalError -
pool_pre_ping=True：每次取连接前发一条SELECT 1检活，代价小但能拦截大量已断连却未被发现的“僵尸连接”
异步场景下 create_async_engine 怎么配池？
用 asyncpg 或 aiomysql 时，create_async_engine 的池行为和同步版不同：它不复用物理连接，而是为每个协程分配独立连接上下文。所以 pool_size 实际控制的是连接池中可复用的连接实例数，且必须配合 await engine.dispose() 显式释放。
常见坑：
- 忘记在 FastAPI 的
lifespan或shutdown中调用engine.dispose()，导致连接泄漏，进程重启后旧连接堆积 - 误以为
max_overflow对 async 有效——其实 asyncpg 自身管理连接队列，SQLAlchemy 层的max_overflow被忽略 - 没关
pool_pre_ping：async 版本支持，但会引入额外 await，高频小查询下建议关掉，改用更轻量的健康检查逻辑
怎么验证连接池真正在工作？
光看配置没用，得观察运行时行为。最直接的方式是打开 SQLAlchemy 日志：
import logging
logging.getLogger('sqlalchemy.pool').setLevel(logging.INFO)
你会看到类似这样的输出：
INFO:sqlalchemy.pool.impl.QueuePool:Created new connection <connection object at> INFO:sqlalchemy.pool.impl.QueuePool:Connection <connection object at> checked out from pool INFO:sqlalchemy.pool.impl.QueuePool:Connection <connection object at> being returned to pool </connection></connection></connection>
重点关注三点：
- “Created new connection” 是否频繁出现？如果是，说明
pool_size太小或pool_recycle过短 - “checked out” 和 “being returned” 是否基本成对？不成对意味着连接没被正确 close 或 session 没 commit/rollback
- 有没有 “Connection invalidated”？大概率是
pool_pre_ping发现了坏连接并剔除——这是正常保护机制
真正难调的是连接泄漏：一个请求结束后，连接没归还池子，久而久之池子被掏空。这种问题往往藏在未关闭的 Session、未 commit 的事务、或 try/except 里漏了 session.close() 的分支里。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
