Django 中手动插入带 ID 的记录导致主键冲突的解决方案

先来看一个非常典型的场景：你在 Django 项目里，一时图方便，直接对着数据库跑了一条 SQL——INSERT INTO blogs_blog (id, text, date_added) VALUES (21, 'test21', now()::timestamptz)。记录成功写进去了，没什么异常提示。但等回过头来，你打开 Django Admin 或者通过 ModelForm 新建一条记录时，啪，报错了：

IntegrityError at /add_new_blog/
duplicate key value violates unique constraint "blogs_blog_pkey"
DETAIL:  Key (id)=(21) already exists.

这事儿看起来像是 Django “没看到”你手动插进去的那条数据，但实际情况恰好相反——Django 知道 id=21 这条记录存在，可它偏偏还是试图再创建一个 id 为 21 的对象。问题出在哪儿？

答案很简单：主键生成机制失步了。

根本原因：数据库序列没跟上节奏

Django 的默认主键（AutoField）在 PostgreSQL 里，是靠底层的 SERIAL 类型 和它绑定的那个序列号生成器（sequence） 来工作的。比如 blogs_blog_id_seq 这个序列，就是专门为 Blog.id 提供下一个数字用的。

当你绕过 Django 直接执行 INSERT ... VALUES (21, ...) 的时候，数据库确实老老实实把 id=21 这条记录写进去了。但问题在于：这个操作并不会自动通知序列“我已经用掉 21 了，你该往前挪一步了”。

于是，下一次 Django 调用 nextval('blogs_blog_id_seq') 时，序列还是懵懵懂懂地返回一个 21——甚至更小的数字。主键冲突就此产生。

你可以用下面这条 SQL 验证一下当前序列的状态：

SELECT last_value, is_called FROM blogs_blog_id_seq;

正确解法：手动重置序列

既然序列落下了，那就帮它追上来。执行下面这条 SQL，就可以把序列更新为当前表中最大 id 的下一个整数：

-- 方法一：基于当前表最大 id 自动设置（推荐）
SELECT setval('blogs_blog_id_seq', (SELECT MAX(id) FROM blogs_blog) + 1);

-- 方法二：如果你已知最大 id 是 21，也可以显式设置为 22
SELECT setval('blogs_blog_id_seq', 22);

两种方法都能达到目的。不过，如果你不确定序列的名字怎么办？在 PostgreSQL 里，序列的命名规则通常是 <表名>_<字段名>_seq。更保险的做法是用这条命令来确认：

SELECT pg_get_serial_sequence('blogs_blog', 'id');

为什么不该手动指定 id？

问题虽然解决了，但有句话还是得说——手动指定主键这件事，本身就是一个危险动作。原因有几个：

• 破坏了 Django 的抽象层：主键是 ORM 内部的标识符，从设计上来说并不需要人为干预。你一旦插手，就等于在告诉 Django“你别管了，我来”，但 Django 的那套机制并不会就此停工。
• 容易引发竞态风险：在多进程或多线程的环境下，手动赋值几乎就是给自己挖坑。两个进程同时插入，一个指定了 21，另一个也指定了 21——冲突几乎是必然的。
• 迁移和数据备份会埋雷：dumpdata 和 loaddata 默认不会导出和恢复序列的状态。你以为数据导过去了，结果一跑又炸了。
• ORM 的很多方法会失效：Model.sa ve()、get_or_create() 这些常用的手段，都是建立在“id 由数据库自动生成”这个假设上的。一旦这个假设不成立，可能出现各种匪夷所思的异常。

所以，正确的做法其实很简单：永远让数据库和 ORM 去控制主键。

# ✅ 推荐：不传 id，由数据库自动生成
blog = Blog.objects.create(text="A blog #1")  # id 自动分配

# ✅ Django Admin / ModelForm 默认就是如此，无需额外配置

# ✅ 使用 bulk_create 时，也记得省略 id 字段
Blog.objects.bulk_create([
    Blog(text="Bulk item 1"),
    Blog(text="Bulk item 2"),
])

开发阶段的预防措施

如果你们团队里有人就是管不住手动插数据的手，或者你希望从流程上就把这条路堵死，可以考虑下面几条预防措施：

1. 在开发环境禁用手动 ID 插入
   在 settings.py 中配置数据库选项（仅限 PostgreSQL），并配合数据库权限控制，强制所有操作走 ORM 流程。

   DATABASES = {
       'default': {
           # ...
           'OPTIONS': {
               'options': '-c default_transaction_read_only=off'
           }
       }
   }

2. 准备自动化序列修复脚本
   创建一个 Django management command，比如 python manage.py fix_sequences，在内部调用 setval 批量修复所有模型的序列。这条命令可以在部署后、做数据迁移后或者定期跑一遍。

3. 切换到 BigAutoField（Django 3.2+）
   在 settings.py 中全局启用更大范围的主键类型，既能降低溢出的概率，也能减少人工干预的冲动。

   DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

总结

把这个原则坚持住，duplicate key violates unique constraint 这个错误就很难再找上你了。代码也好，数据一致性也好，都会清爽很多。