4.9 KiB
2026-04-02 RDS PgBouncer 命名游标问题记录
背景
生产环境在 Django Admin 页面访问 SalesItem 编辑页时出现如下错误：
ProgrammingError at /admin/shipment/salesitem/1/change/
cursor "_django_curs_128437320623808_sync_1" already exists
本地开发/测试环境未复现该问题。
现象
- 出错页面：
/admin/shipment/salesitem/<id>/change/ - 错误类型：PostgreSQL
ProgrammingError - 关键错误信息：
cursor "... already exists" - 特征：属于数据库连接/游标状态错误，而不是表结构错误
排查结论
1. 不是 migrate 未执行导致
本次错误不符合迁移缺失的典型表现。
如果是 migration 未执行，通常会看到：
- 某字段不存在
- 某表不存在
- 约束不存在
- 类型不匹配
而本次是“命名游标已经存在”，属于运行时数据库连接状态问题。
2. 当前 SalesItem Admin 实现本身没有明显异常
shipment 模块中的 admin 配置较为简单，没有明显会主动触发复杂命名游标行为的自定义逻辑：
因此本问题更像是生产环境数据库接入方式引发，而不是该页面逻辑本身写坏。
3. 根因判断：阿里云 RDS 自带 PgBouncer/连接池 与 Django server-side cursors 兼容性问题
生产环境已确认使用“阿里云 RDS 自带代理/连接池”。
Django 在 PostgreSQL 下会在部分场景使用 server-side cursors（尤其与 QuerySet.iterator() 相关）。
当应用经过连接池/代理访问数据库时，连接池不能稳定保证命名游标依赖的“同一物理连接上下文”，从而可能触发：
- 命名游标残留
- 游标状态错乱
cursor "... already exists"
这类问题在连接池场景下比直连 PostgreSQL 更容易出现。
代码与配置侧观察
数据库配置
项目数据库配置位于：
原有配置特征：
- 使用 PostgreSQL
- 支持
CONN_MAX_AGE - 未显式设置
DISABLE_SERVER_SIDE_CURSORS
项目内的连接池配置
仓库自带的 PgBouncer 配置位于：
仓库内自建 PgBouncer 使用的是 session 模式。
但生产环境此次问题来自阿里云 RDS 自带代理/连接池，实际行为应以云侧代理为准，不能简单等同于本仓库自带 PgBouncer 配置。
修复决策
考虑到：
- 生产环境不能放弃连接池
- 该系统存在较多大查询
- 生产已经出现与命名游标相关的实际错误
最终决定采用 Django 官方支持的兼容方案：
在数据库配置中加入：
'DISABLE_SERVER_SIDE_CURSORS': True,
并保留：
'CONN_MAX_AGE': env.int('CONN_MAX_AGE', default=0),
修复位置
已在以下位置加入配置：
配置位置为 DATABASES['default'] 顶层，与 ENGINE、HOST、PORT、CONN_MAX_AGE 同级，不放在 OPTIONS 中。
采用该修复的原因
为什么不优先怀疑 migration
因为错误类型明显属于连接/游标状态，不属于 schema 不一致。
为什么不取消连接池
生产环境仍需要连接池承载系统中的大查询与整体数据库连接管理。
为什么选择禁用 server-side cursors
这是 Django 官方针对连接池/代理场景给出的标准兼容方向之一。
对当前项目而言，这一决策的风险低于继续保留命名游标并承受生产不稳定性。
可能的副作用
启用 DISABLE_SERVER_SIDE_CURSORS=True 后：
- 普通页面和常规 ORM 查询通常不会受功能性影响
- 依赖
QuerySet.iterator()的超大结果集遍历，可能失去 server-side cursor 带来的部分性能/内存优势
项目中需要后续重点观察的批量遍历代码包括：
也就是说，该修复更可能带来“部分后台任务性能特征变化”，而不是“开发环境或生产环境无法正确运行”。
对开发环境的影响判断
开发环境同样可以启用 DISABLE_SERVER_SIDE_CURSORS=True，不会导致系统无法运行。
主要影响仍然是：
- 大结果集遍历时的性能和内存行为可能更保守
但这不属于严重副作用。
结论
本次问题定性为：
- 生产环境数据库连接池代理与 Django server-side cursors 的兼容性问题
本次修复决策为：
- 保留连接池
- 在 Django 数据库配置中启用
DISABLE_SERVER_SIDE_CURSORS=True
该决策用于降低生产环境中命名游标相关错误的出现概率，并保持系统整体连接池架构不变。