如何正确关闭SQLAlchemy连接避免QueuePool超时错误

问题场景 #

使用Flask+SQLAlchemy连接AWS RDS上的PostgreSQL数据库，频繁触发如下错误：

sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached

错误导致服务器无响应，只能通过重启恢复。代码包含两种数据库操作模式：

1. 基于模型的查询（无问题）：

users = User.query.order_by(desc(User.created))\
                .limit(users_per_page)\
                .offset((page_number - 1) * users_per_page)\
                .all()

2. 基于会话的直接查询（部署后出现问题）：

with contextlib.closing(db.session) as session:
   data = session.query(task_function, Stat.activity, func.count()).filter(
                        Stat.created.in_(subq)).group_by(period_function, 
                        Stat.activity_detail).order_by(desc(period_function))

未手动创建create_engine，无法直接套用常规连接池配置方案。

问题原因 #

使用contextlib.closing(db.session)时，若未显式提交/回滚事务，会话不会正确结束，占用的数据库连接无法释放回连接池。随着请求积累，连接池被耗尽，最终触发超时错误。

解决方案 #

通过显式提交事务+主动清理会话，确保连接及时释放：

1. 在with代码块内添加事务结束逻辑（提交或回滚）
2. 编写统一的会话清理函数，处理事务收尾与会话关闭：

import contextlib
from sqlalchemy.exc import SQLAlchemyError

def cleanup_session(session):
    try:
        # 提交事务，只读场景也可使用session.rollback()来结束事务
        session.commit()
    except SQLAlchemyError:
        session.rollback()
        raise
    finally:
        # 关闭会话，将连接放回连接池
        session.close()

# 使用示例
with contextlib.closing(db.session) as session:
    data = session.query(task_function, Stat.activity, func.count()).filter(
                        Stat.created.in_(subq)).group_by(period_function, 
                        Stat.activity_detail).order_by(desc(period_function)).all()
    cleanup_session(session)

该方案可避免会话挂起，确保连接池中的连接被正常回收，当前连接数已恢复正常。

内容的提问来源于stack exchange，提问作者mimic