# 2026-04-02 RDS PgBouncer 命名游标问题记录

## 背景

生产环境在 Django Admin 页面访问 `SalesItem` 编辑页时出现如下错误：

```text
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 配置较为简单，没有明显会主动触发复杂命名游标行为的自定义逻辑：

- 参考：[shipment/admin.py](/home/f/coding/flower/shipment/admin.py)

因此本问题更像是生产环境数据库接入方式引发，而不是该页面逻辑本身写坏。

### 3. 根因判断：阿里云 RDS 自带 PgBouncer/连接池 与 Django server-side cursors 兼容性问题

生产环境已确认使用“阿里云 RDS 自带代理/连接池”。

Django 在 PostgreSQL 下会在部分场景使用 server-side cursors（尤其与 `QuerySet.iterator()` 相关）。  
当应用经过连接池/代理访问数据库时，连接池不能稳定保证命名游标依赖的“同一物理连接上下文”，从而可能触发：

- 命名游标残留
- 游标状态错乱
- `cursor "... already exists"`

这类问题在连接池场景下比直连 PostgreSQL 更容易出现。

## 代码与配置侧观察

### 数据库配置

项目数据库配置位于：

- [flower/settings.py](/home/f/coding/flower/flower/settings.py)

原有配置特征：

- 使用 PostgreSQL
- 支持 `CONN_MAX_AGE`
- 未显式设置 `DISABLE_SERVER_SIDE_CURSORS`

### 项目内的连接池配置

仓库自带的 PgBouncer 配置位于：

- [deploy/pgbouncer/pgbouncer.ini](/home/f/coding/flower/deploy/pgbouncer/pgbouncer.ini)

仓库内自建 PgBouncer 使用的是 `session` 模式。  
但生产环境此次问题来自阿里云 RDS 自带代理/连接池，实际行为应以云侧代理为准，不能简单等同于本仓库自带 PgBouncer 配置。

## 修复决策

考虑到：

- 生产环境不能放弃连接池
- 该系统存在较多大查询
- 生产已经出现与命名游标相关的实际错误

最终决定采用 Django 官方支持的兼容方案：

在数据库配置中加入：

```python
'DISABLE_SERVER_SIDE_CURSORS': True,
```

并保留：

```python
'CONN_MAX_AGE': env.int('CONN_MAX_AGE', default=0),
```

## 修复位置

已在以下位置加入配置：

- [flower/settings.py](/home/f/coding/flower/flower/settings.py)

配置位置为 `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 带来的部分性能/内存优势

项目中需要后续重点观察的批量遍历代码包括：

- [printing/tasks.py](/home/f/coding/flower/printing/tasks.py)
- [api_v1/external_product_image_backfill.py](/home/f/coding/flower/api_v1/external_product_image_backfill.py)

也就是说，该修复更可能带来“部分后台任务性能特征变化”，而不是“开发环境或生产环境无法正确运行”。

## 对开发环境的影响判断

开发环境同样可以启用 `DISABLE_SERVER_SIDE_CURSORS=True`，不会导致系统无法运行。

主要影响仍然是：

- 大结果集遍历时的性能和内存行为可能更保守

但这不属于严重副作用。

## 结论

本次问题定性为：

- **生产环境数据库连接池代理与 Django server-side cursors 的兼容性问题**

本次修复决策为：

- **保留连接池**
- **在 Django 数据库配置中启用 `DISABLE_SERVER_SIDE_CURSORS=True`**

该决策用于降低生产环境中命名游标相关错误的出现概率，并保持系统整体连接池架构不变。