唯一约束违反:重复键
快速摘要
你尝试在具有唯一约束的列中插入重复值 —— 数据库拒绝了该操作。
为什么发生
应用尝试插入表中已存在的键的行
竞态条件导致两个并发插入同时尝试相同的键
更新将列值改为另一行中已存在的值
最小示例
✗ 错误代码
await db.query('INSERT INTO users (email, name) VALUES ($1, $2)', ['[email protected]', 'John']);
// Error: duplicate key value violates unique constraint on email✓ 修复代码
await db.query(
'INSERT INTO users (email, name) VALUES ($1, $2) ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name',
['[email protected]', 'John']
); // upsert: insert or update if exists使用 ON CONFLICT DO UPDATE 将插入变为 upsert,通过更新现有行而非失败来处理重复键。
如何诊断
检查错误消息中的约束名称和重复值
查询表以确认重复值已存在
查看插入/更新逻辑以理解为何尝试了重复值
如何修复
使用 INSERT ON CONFLICT DO NOTHING 或 INSERT ... ON DUPLICATE KEY UPDATE 优雅处理重复
插入前检查是否存在,或使用 upsert/merge 语句
使用序列或 UUID 生成唯一键以避免冲突
如何预防
对幂等插入使用 upsert 模式(ON CONFLICT、ON DUPLICATE KEY UPDATE)
使用数据库序列或 UUID 而非应用逻辑生成唯一标识符
相关资源
相关术语
相关课程
- 约束
学习约束。