如何高效遍历Django百万级QuerySet并解决命名游标失效报错

安全阿岳

2026-9-26

错误根因

这个django.db.utils.ProgrammingError: named cursor isn't valid anymore错误是PostgreSQL数据库特性和你的代码逻辑冲突导致的：

Django对PostgreSQL后端调用QuerySet.iterator()时，默认会使用服务端命名游标流式加载数据，避免一次性加载全量数据到内存
PostgreSQL的服务端命名游标生命周期和当前事务绑定，你每1000条提交一次事务，提交后原有游标会被自动销毁
你代码前2000条运行正常是因为Django默认fetchmany的批次大小就是2000，前两批数据已经拉到客户端了，第三次要拉取新数据时游标已经失效，就抛出了异常。

可行解决方案

方案1：分页分批遍历（兼容性最好，推荐）

放弃iterator()，改用固定大小分页的方式遍历，完全不依赖长生命周期的游标，适配所有Django版本：

from django.db import transaction
from django.conf import settings

settings.DEBUG = False
# 每批处理1000条，可根据服务器性能调整
BATCH_SIZE = 1000

filter_condition = dict(some_criteria=123)
total = MyModel.objects.filter(**filter_condition).count()
processed = 0

while True:
    # 按主键排序保证分页顺序稳定，避免删除过程中出现数据遗漏
    batch = MyModel.objects.filter(**filter_condition).order_by('pk')[:BATCH_SIZE]
    if not batch:
        break
    # 每批一个独立事务，提交后自动释放资源
    with transaction.atomic():
        for record in batch:
            processed += 1
            if processed == 1 or not processed % 100 or processed == total:
                print(f'{processed} of {total} {processed / total * 100:.2f}%: {record}')
            record.delete()

如果不需要触发模型的delete信号、也不需要单条记录的前置校验，可以直接用批量删除替代单条循环删除，性能提升10倍以上：

# 把for循环里的单条删除替换成批量删除
batch.delete()
processed += len(batch)

方案2：关闭iterator的命名游标（适配Django 4.2+）

如果必须使用iterator()，可以在调用时显式关闭命名游标，改用客户端游标，事务提交不会影响游标可用性：

# 原有其他代码不变，仅修改iterator调用
for record in qs.iterator(named_cursor=False, chunk_size=1000):
    # 原有处理逻辑不变

方案3：全局关闭服务端游标（适配低版本Django）

如果使用的是4.2以下的Django版本，没有named_cursor参数，可以在项目settings.py的数据库配置里添加参数全局关闭服务端命名游标：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        # 其他原有配置
        'DISABLE_SERVER_SIDE_CURSORS': True,
    }
}

注意这个配置是全局生效的，会影响所有QuerySet.iterator()的执行逻辑。

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