Skip to content

唯一约束违反:重复键

快速摘要

你尝试在具有唯一约束的列中插入重复值 —— 数据库拒绝了该操作。

为什么发生

  • 应用尝试插入表中已存在的键的行

  • 竞态条件导致两个并发插入同时尝试相同的键

  • 更新将列值改为另一行中已存在的值

最小示例

✗ 错误代码
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 而非应用逻辑生成唯一标识符

相关资源

相关术语

相关课程

← 返回语言