Drizzle ORM 中 onConflictDoNothing 与 returning 的配合问题解析

问题现象

在使用 Drizzle ORM 进行数据库操作时，开发者发现当使用 onConflictDoNothing() 与 returning() 方法组合时，如果遇到数据冲突情况，returning() 方法不会返回任何数据。具体表现为：

1. 首次插入数据时，returning() 能正确返回插入的数据
2. 当尝试插入相同数据（产生冲突）时，returning() 返回空数组

技术背景

这个问题实际上源于底层数据库引擎的行为，而非 Drizzle ORM 本身的实现问题。在 SQLite 和 PostgreSQL 等数据库中：

• ON CONFLICT DO NOTHING 语句在遇到冲突时会静默跳过该行插入
• 当所有插入行都因冲突被跳过时，数据库不会返回任何行数据
• 这是数据库层面的标准行为，ORM 无法改变这一机制

解决方案

对于需要确保返回数据的场景，开发者可以采用以下替代方案：

1. 使用 onConflictDoUpdate

await db.insert(schema.books)
  .values(book)
  .onConflictDoUpdate({
    target: schema.books.id,
    set: { updatedAt: new Date() } // 设置一个无实际影响的更新
  })
  .returning();

这种方法通过执行一个无害的更新操作，确保数据库总有行可返回。

2. 显式处理空结果

const result = await db.insert(schema.books)
  .values(book)
  .returning()
  .onConflictDoNothing();

if (result.length === 0) {
  // 处理冲突情况
  const existing = await db.select().from(schema.books)
    .where(eq(schema.books.id, book.id));
  // 使用 existing 数据
}

3. 错误捕获方案

try {
  const result = await db.insert(schema.books)
    .values(book)
    .returning()
    .onConflictDoNothing();
} catch (err) {
  if (err instanceof Error && 
      err.message.includes("values() must be called with at least one value")) {
    // 处理全冲突情况
  }
}

最佳实践建议

1. 明确业务需求：首先确定是否真的需要在冲突时获取数据，或许业务逻辑可以直接使用冲突信息

2. 类型安全：虽然返回类型是数组，但应该总是处理空数组情况，避免运行时错误

3. 性能考量：onConflictDoUpdate 虽然能解决问题，但会产生额外的写操作，在高并发场景需谨慎使用

4. 文档注释：在代码中添加清晰注释，说明这种特殊行为的来源，方便后续维护

总结

这个问题展示了 ORM 与底层数据库交互时的一个典型边界情况。作为开发者，理解数据库引擎的行为特性非常重要。Drizzle ORM 在此场景下保持了与底层数据库一致的行为，虽然可能不符合部分开发者的直觉预期，但这种设计保持了透明性和一致性。

在实际开发中，建议根据具体业务场景选择最适合的解决方案，并在团队内部形成统一的处理规范，以确保代码的可维护性和可靠性。