Flask应用闲置后出现SQLAlchemy连接错误及回滚问题求解

问题场景 #

Flask应用闲置约一日后首次访问，抛出以下错误：

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) SSL connection has been closed unexpectedly

重试请求时，进一步触发：

sqlalchemy.exc.PendingRollbackError: Can't reconnect until invalid transaction is rolled back.

已尝试的配置：

• 添加PostgreSQL连接keepalive参数：

db = SQLAlchemy(app, engine_options={'connect_args': {
'keepalives': 1,
'keepalives_idle': 30,
'keepalives_interval': 10,
'keepalives_count': 5
}})

• 启用pool_pre_ping：

app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {"pool_pre_ping": True}

出错查询代码：

stmt = db.session.query(User).filter(User.username == username)
account = db.session.scalars(stmt).first()

解决方案 #

1. 调整连接池回收策略 #

pool_pre_ping仅能检测死连接，但如果连接池内连接的存活时间超过数据库端的闲置超时阈值，仍会触发断开问题。需设置连接池主动回收时间，确保早于数据库的闲置超时：

app.config['SQLALCHEMY_ENGINE_OPTIONS'] = {
    "pool_pre_ping": True,
    "pool_recycle": 3600  # 1小时回收一次连接，需小于数据库闲置超时时间
}

注意：pool_recycle的值要小于数据库配置的闲置超时（例如云服务商数据库通常设置为7小时，这里设1小时更稳妥）。

2. 捕获异常并强制回滚失效事务 #

当出现连接异常时，当前会话的事务已失效，必须手动回滚才能重新使用会话。可以在数据库操作层或全局捕获异常：

from sqlalchemy.exc import OperationalError, PendingRollbackError

try:
    stmt = db.session.query(User).filter(User.username == username)
    account = db.session.scalars(stmt).first()
except OperationalError:
    db.session.rollback()
    # 重试查询
    stmt = db.session.query(User).filter(User.username == username)
    account = db.session.scalars(stmt).first()
except PendingRollbackError:
    db.session.rollback()
    account = None

也可通过Flask全局错误处理器统一处理：

@app.errorhandler(OperationalError)
def handle_db_conn_error(e):
    db.session.rollback()
    return "数据库连接异常，已重试", 500

@app.errorhandler(PendingRollbackError)
def handle_rollback_error(e):
    db.session.rollback()
    return "事务异常，已回滚", 500

3. 规范会话使用方式（推荐） #

每次数据库操作使用上下文管理器自动管理事务，避免会话长期持有无效连接：

def get_user_by_username(username):
    with db.session.begin():
        stmt = db.session.query(User).filter(User.username == username)
        return db.session.scalars(stmt).first()

这种方式会在操作完成后自动提交/回滚事务，确保会话始终处于有效状态。

4. 验证数据库端配置 #

• 检查PostgreSQL的tcp_keepalives_idle、idle_in_transaction_session_timeout等参数，确保客户端keepalive配置与数据库端匹配。
• 若使用云服务商数据库（如AWS RDS），确认其闲置连接超时设置，调整pool_recycle值小于该阈值。

5. 确认系统级TCP keepalive生效 #

部分环境（如Docker、云服务器）可能禁用TCP keepalive，可通过sysctl net.ipv4.tcp_keepalive_time检查系统默认配置，确保客户端keepalive参数能正常生效。

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