3. Engine与连接管理

在 SQLAlchemy 中，Engine 是应用与数据库之间的总入口。它并不是一条数据库连接，而是一个“连接工厂 + 连接池 + 方言适配器”的组合体。理解这一点非常关键：调用 engine.connect() 时，真正发生的是从连接池借出一条 Connection；调用 engine.dispose() 时，销毁的是整个池及其持有的物理连接。把 Engine 当成“连接”来管理，是很多连接泄漏和性能问题的根源。

Engine 的创建与关键配置

创建 Engine 的标准方式是 create_engine()。URL 决定方言与驱动，其余参数决定池行为与调试能力。下面是一个面向 PostgreSQL 的典型配置示例：

from sqlalchemy import create_engine

engine = create_engine(
    "postgresql+psycopg2://app:secret@db.internal:5432/orders",
    pool_size=10,          # 池中常驻连接数
    max_overflow=20,       # 峰值可临时超出的连接数
    pool_timeout=30,       # 借连接最长等待秒数
    pool_recycle=1800,     # 连接存活超过 1800s 则回收重建
    pool_pre_ping=True,    # 借出前先 ping，剔除失效连接
    echo=False,            # 生产环境关闭 SQL 回显
    future=True,           # 使用 2.0 风格 API
)

其中 pool_size + max_overflow 是该 Engine 能同时持有的物理连接上限。以示例参数计算，上限为 30 条。若应用有 8 个进程，每个进程都创建同样的 Engine，则数据库侧理论最大连接数为 8 × 30 = 240，这个数字必须与数据库的 max_connections 以及中间件（如 PgBouncer）容量对齐，否则高峰期会出现“连接被拒”而非“等待超时”。

连接池参数之间的关系

连接池参数不是孤立的，它们共同决定“借出—等待—回收—重建”的行为。下图展示了 Engine 内部结构、连接池状态迁移以及多数据库 Engine 的并存关系，可作为配置与排障时的参照：

应用代码 session / connection Engine（连接工厂 + 池 + 方言） 连接池 pool_size=10 溢出区 max_overflow=20 方言 / 驱动适配 psycopg2 · asyncpg · pymysql 数据库 max_connections connect() 物理连接 连接生命周期状态 空闲 Idle 借出 Checked-out 使用中 In-use 归还 Returned 回收/重建 归还后回到空闲池，等待下次复用 多数据库 Engine 并存 Engine A · 订单库 pool_size=10 Engine B · 用户库 pool_size=5 Engine C · 报表只读 pool_recycle=600 每个 Engine 独立池，互不共享连接 总连接数 = 各池上限之和

连接生命周期与归还语义

一条物理连接在池中的典型生命周期是：创建 → 空闲 → 借出 → 使用 → 归还 → 复用或回收。SQLAlchemy 的 Connection 对象在 close() 时并不真正关闭物理连接，而是将其归还池中；只有 engine.dispose() 或池回收策略触发时，物理连接才被关闭。因此，判断是否泄漏的标准不是“有没有调用 close”，而是“借出的连接是否在合理时间内归还”。

使用 with engine.connect() as conn: 或 with Session(engine) as session: 能保证异常路径下也归还连接。相反，手动 conn = engine.connect() 后忘记 conn.close()，或在长生命周期对象中持有 Connection，都会导致池中可用连接逐渐耗尽，最终在 pool_timeout 后抛出 TimeoutError。

多数据库连接的组织方式

当系统需要访问多个数据库时，推荐为每个数据库创建独立 Engine，并通过字典或依赖注入统一管理。例如：

engines = {
    "orders": create_engine(ORDERS_URL, pool_size=10, max_overflow=20),
    "users":  create_engine(USERS_URL,  pool_size=5,  max_overflow=10),
    "report": create_engine(REPORT_URL, pool_size=3,  max_overflow=5, pool_recycle=600),
}

关键原则是：不要跨库复用同一个 Engine，也不要在请求处理过程中动态创建 Engine。Engine 应当是进程级单例，在应用启动时创建，在应用关闭时统一 dispose()。对于只读报表库，可以单独设置更短的 pool_recycle，因为只读连接更容易被中间件或防火墙静默断开。

连接泄漏的排查方法

连接泄漏的典型症状是：应用运行一段时间后，请求开始变慢，随后出现 QueuePool limit of size 10 overflow 20 reached, connection timed out。排查时可按以下顺序进行：

  1. 确认池状态：通过 engine.pool.status() 查看当前池中连接数、借出数和溢出数。若 checkedout 持续接近上限且不下降，基本可判定为泄漏。
  2. 定位未归还点：检查所有 engine.connect() 和 Session() 的调用位置，确认是否都在 with 块或 try/finally 中关闭。
  3. 检查长事务：未提交或未回滚的事务会一直占用连接。可在数据库侧查询 pg_stat_activity 中状态为 idle in transaction 的会话。
  4. 检查全局对象：确认没有把 Connection 或 Session 保存在模块级变量、缓存或类属性中。

常见误区：把 Session 当作全局单例长期复用。Session 不是线程安全的，且会持有连接直到 close()。正确做法是每个请求或每个工作单元创建一个 Session，用完即关。

工程实践建议

在生产环境中，建议将 Engine 配置集中到一个模块，并通过环境变量区分开发、测试和生产。以下是一份可直接参考的配置检查清单：

检查项建议值 / 做法目的
pool_pre_pingTrue剔除已被数据库或中间件断开的失效连接
pool_recycle小于数据库 wait_timeout，如 1800s避免使用超过服务端存活上限的连接
pool_timeout10～30s快速失败，避免请求无限等待
连接上限核算进程数 × (pool_size + max_overflow) ≤ 数据库容量防止连接风暴打满数据库
Engine 生命周期进程级单例，启动创建、关闭 dispose避免重复建池和连接泄漏
Session 作用域每请求 / 每工作单元保证连接及时归还

最后，建议在应用关闭钩子中显式调用 engine.dispose()，确保所有池中连接被干净关闭。对于使用多进程部署（如 Gunicorn 多 worker）的场景，每个 worker 进程会各自持有一个 Engine 和连接池，因此连接上限必须按进程数放大核算，而不是按单个 Engine 计算。把 Engine 当作“进程级资源”来规划，是连接管理从能用走向稳定的关键一步。

← 上一章 📖 返回目录 下一章 →