连接池耗尽的典型表现是flask应用返回timeouterror: queuepool limit of size x overflow x reached或请求卡在engine.connect()、session.execute()上，根本原因是连接未及时归还，而非并发过高；需通过teardown_appcontext调用db.session.close()、合理设置pool_size与max_overflow、启用pool_pre_ping和pool_recycle来解决。
连接池耗尽的典型表现不是并发高，而是连接没归还
Flask 应用突然返回 TimeoutError: QueuePool limit of size X overflow X reached，或大量请求卡在 engine.connect()、session.execute() 上——这不是流量突增导致的，八成是某处 session 没关、db.session.remove() 没调、或后台线程复用了主线程 session。连接池满 ≠ 连接数不够，而是连接被“占着不放”。
pool_size 和 max_overflow 要按真实负载反推，别套默认值
默认 pool_size=5、max_overflow=10 只适合本地调试。生产环境必须结合 QPS 和 DB 操作平均耗时估算：
- 例如：100 QPS × 0.2 秒平均 DB 耗时 ≈ 20 个活跃连接 → 建议
pool_size=15+max_overflow=5 - 总预留连接数 = 单实例
pool_size + max_overflow× 实例数，不能超过数据库max_connections（如 PostgreSQL 推荐单实例 ≤100） - 别按 CPU 核数设 pool_size —— Python 的 GIL 和 I/O 等待会让实际并发远低于理论值
SQLAlchemy 3.x 必须用 SQLALCHEMY_ENGINE_OPTIONS 配 pool_recycle
MySQL 或云 RDS 常把 wait_timeout 设为 300–900 秒，而 Flask-SQLAlchemy 不主动验证空闲连接。若不干预，拿一个已被 MySQL 断开的连接去查，就会报 pymysql.err.OperationalError: (2013, 'Lost connection to MySQL server during query')。
正确做法是让连接池在失效前主动丢弃旧连接：
- 先查清数据库真实值：
SHOW VARIABLES LIKE 'wait_timeout';（注意：不是interactive_timeout） - 设
pool_recycle比它小 30–60 秒，比如 MySQL 返回900，就设840 - 新版（≥3.0）必须写进
SQLALCHEMY_ENGINE_OPTIONS：app.config["SQLALCHEMY_ENGINE_OPTIONS"] = {"pool_recycle": 840} - 设太小（如 30）会引发建连风暴；设太大（≥wait_timeout）等于没设；设 -1 是自毁
scoped_session 的 close 不等于 remove，teardown_appcontext 才是关键
手动创建 session = Session() 后只调 session.close() 是错的 —— 它只是清理 session 状态，不释放底层连接。用 Flask-SQLAlchemy 的 db.session 时，必须靠 db.session.remove() 归还连接。
- 正确姿势：注册
@app.teardown_appcontext钩子，里面调db.session.remove() - 别在视图里
try/except但漏掉finally: session.close()—— 尤其有return提前退出时 - Celery 或线程中禁止复用
db.session，必须用原始engine构建新Session，操作完显式session.close()
pool_recycle 只影响空闲连接，正在执行长查询的连接不会被中途回收；但如果你在 Celery 任务里跑几小时的 job，又没手动 db.session.close()，那个连接就一直卡在池里，直到超时或进程重启。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
