Python 数据库问题：连接超时与连接池配置

Python 应用在高并发或长时间运行场景下，常因数据库连接管理不当出现“连接超时”错误。这类问题通常表现为 OperationalError: (2013, 'Lost connection to MySQL server during query') 或类似提示。根本原因往往不是网络故障，而是连接被数据库服务器主动关闭，而应用未正确复用或重建连接。解决的关键在于合理配置连接池和超时参数。

诊断连接超时的常见原因

检查以下三个核心配置项是否匹配：

1. 数据库服务器的 wait_timeout：MySQL 默认为 28800 秒（8 小时），表示非交互式连接在无操作后多久被断开。
2. 应用层连接池的 max_lifetime：连接池中单个连接的最大存活时间。
3. 连接池的 recycle 或 stale 检测机制：是否在借出连接前验证其有效性。

若连接池中的连接存活时间超过数据库的 wait_timeout，该连接会被数据库端关闭。当下次应用尝试使用此“僵尸连接”时，就会触发超时错误。

使用 SQLAlchemy 配置稳健的连接池

SQLAlchemy 是 Python 最主流的 ORM 和数据库工具包，其内置连接池可有效规避超时问题。以下是关键配置步骤：

1. 安装依赖
   执行命令安装必要组件：

   pip install sqlalchemy pymysql

2. 创建带超时控制的引擎
   构造数据库连接 URL，并显式设置连接池参数：

   from sqlalchemy import create_engine
   
   DATABASE_URL = "mysql+pymysql://user:password@host:3306/dbname"
   
   engine = create_engine(
       DATABASE_URL,
       pool_size=10,          # 连接池中保持的最小连接数
       max_overflow=20,       # 超出 pool_size 后最多可额外创建的连接数
       pool_pre_ping=True,    # 借出连接前先 ping 测试有效性（关键！）
       pool_recycle=3600,     # 强制回收连接的时间（秒），应小于数据库 wait_timeout
       connect_args={
           "connect_timeout": 10,  # TCP 连接超时（秒）
           "read_timeout": 30,     # 读取超时（秒）
           "write_timeout": 30     # 写入超时（秒）
       }
   )

   • pool_pre_ping=True 是最简单有效的防超时手段，它会在每次从池中获取连接时自动执行轻量级查询（如 SELECT 1），若失败则丢弃旧连接并新建。
   • pool_recycle=3600 表示连接使用 1 小时后强制重建，确保不会超过 MySQL 默认的 8 小时限制。

3. 验证数据库的 wait_timeout 值
   登录 MySQL 并执行：

   SHOW VARIABLES LIKE 'wait_timeout';

   将 pool_recycle 设为该值的 70%~80% 更安全（例如若 wait_timeout=28800，则 pool_recycle=21600）。

手动管理连接时的避坑指南

若未使用 ORM 而直接操作数据库驱动（如 PyMySQL、psycopg2），需自行实现连接复用逻辑：

1. 不要全局保存单一连接对象
   全局连接在长时间运行后必然失效。始终通过函数或上下文管理器按需获取连接。

2. 使用上下文管理器自动清理
   定义一个安全的连接获取函数：

   import pymysql
   from contextlib import contextmanager
   
   @contextmanager
   def get_db_connection():
       conn = None
       try:
           conn = pymysql.connect(
               host='localhost',
               user='user',
               password='password',
               database='dbname',
               connect_timeout=10,
               read_timeout=30,
               write_timeout=30,
               autocommit=True
           )
           # 可选：执行 ping 检测
           conn.ping(reconnect=True)
           yield conn
       finally:
           if conn:
               conn.close()

3. 在业务代码中调用
   使用 with 语句确保连接及时释放：

   with get_db_connection() as conn:
       with conn.cursor() as cursor:
           cursor.execute("SELECT * FROM users WHERE id = %s", (1,))
           result = cursor.fetchone()

不同数据库的超时参数对照表

不同数据库的超时机制名称不同，配置时需对应调整：

注意：PostgreSQL 的连接空闲超时由操作系统 TCP keepalive 控制，通常需在系统层面调整，应用层建议依赖 pool_pre_ping。

高级场景：异步框架中的连接池

在 FastAPI、Tornado 等异步框架中，需使用异步数据库驱动（如 aiomysql、asyncpg）：

1. 使用 aiomysql 配置连接池

   import aiomysql
   import asyncio
   
   async def init_db_pool():
       return await aiomysql.create_pool(
           host='localhost',
           port=3306,
           user='user',
           password='password',
           db='dbname',
           minsize=5,
           maxsize=20,
           connect_timeout=10,
           read_timeout=30,
           write_timeout=30,
           autocommit=True
       )
   
   # 在应用启动时初始化
   pool = asyncio.run(init_db_pool())

2. 使用时从池中获取连接

   async def fetch_user(user_id):
       async with pool.acquire() as conn:
           async with conn.cursor() as cur:
               await cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
               return await cur.fetchone()

异步驱动通常不支持 pool_pre_ping，需自行在 acquire 后执行 await conn.ping() 或捕获异常重建连接。

启用 pool_pre_ping=True 并设置 pool_recycle 小于数据库 wait_timeout，即可解决绝大多数连接超时问题。