PostgreSQL空闲连接对max_connections的影响及FastAPI连接问题排查

问题描述 #

近期调用FastAPI接口时频繁返回500状态码，报错信息为'M': 'sorry, too many clients already'。执行以下查询脚本：

select pid as process_id, 
       usename as username, 
       datname as database_name, 
       client_addr as client_address, 
       application_name,
       backend_start,
       state,
       state_change
from pg_stat_activity;

发现约有50个状态为idle的连接（已建立但未执行任何事务），而PostgreSQL配置中max_connections上限为100。

Idle连接的额外影响 #

除了占用内存，这些idle连接还有以下关键影响：

• 占用连接配额：max_connections统计的是所有状态的连接总数，idle连接会直接占用配额，导致新请求无法建立连接，这正是你遇到报错的直接原因。
• 消耗系统资源：每个PostgreSQL连接对应一个独立进程，即使处于idle状态，也会占用进程表项、文件描述符等系统资源，数量过多会增加操作系统的调度负担。
• 连接泄漏风险：如果idle连接是未正确关闭导致的泄漏，长期积累会耗尽max_connections，甚至引发系统层面的资源耗尽问题。
• 潜在事务隐患：若存在idle in transaction状态的连接（你当前是纯idle，风险较低），会持有未提交事务，导致锁占用、autovacuum无法清理数据等问题。

FastAPI代码问题分析 #

从提供的代码片段来看，get_db_instance的实现符合FastAPI依赖注入规范：

# utils.py
def get_db_instance():
    try:
        db = SessionLocal()
        yield db
    finally:
        db.close()

通过yield返回数据库会话，finally块确保请求结束后一定会关闭会话，理论上不会导致连接泄漏。但需要排查以下可能的问题：

1. SessionLocal连接池配置：检查SessionLocal的创建代码，是否配置了pool_recycle（自动回收长时间idle的连接）、pool_size（限制连接池大小）等参数。如果未设置pool_recycle，当连接长时间idle被PostgreSQL主动断开后，SQLAlchemy可能不会及时清理无效连接，导致连接池积累无效连接。
2. 路由依赖使用是否规范：确认所有需要数据库连接的FastAPI路由，都通过Depends(get_db_instance)获取会话，有没有地方手动调用SessionLocal()创建会话但忘记调用close()？这种情况会直接导致连接泄漏。
3. 事务异常处理：add函数中执行commit()后，若出现异常是否有rollback()操作？虽然这不会直接导致连接泄漏，但可能引发事务残留，间接影响连接状态。

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