Kysely 中处理 PostgreSQL 部分唯一索引冲突的正确方式

在使用 Kysely 这个 TypeScript SQL 查询构建器与 PostgreSQL 交互时，处理部分唯一索引(Partial Unique Index)的冲突需要特别注意语法结构。部分唯一索引是 PostgreSQL 中一种强大的特性，它允许我们只在满足特定条件时强制唯一性约束。

部分唯一索引基础

在 PostgreSQL 中，我们可以创建这样的部分唯一索引：

CREATE TABLE my_table (
    id SERIAL,
    my_identifier VARCHAR,
    my_type VARCHAR,
    value TEXT
);

CREATE UNIQUE INDEX my_partial_unique_index 
ON my_table(my_identifier) 
WHERE my_type = 'foo';

这个索引确保了当 my_type 为 'foo' 时，my_identifier 列的值必须唯一。

原生 SQL 中的冲突处理

在原生 PostgreSQL 中，我们可以这样处理冲突：

INSERT INTO my_table (my_identifier, my_type, value) 
VALUES ('123', 'foo', 'bar') 
ON CONFLICT (my_identifier) WHERE my_type = 'foo' 
DO UPDATE SET value = 'baz';

Kysely 中的正确实现方式

在 Kysely 中，正确的实现方式是使用 onConflict 构建器的链式方法，而不是直接使用原始 SQL 表达式：

await db
  .insertInto("my_table")
  .onConflict((oc) =>
    oc
      .column("my_identifier")
      .where("my_type", "=", "foo")
      .doUpdateSet({ value: "baz" })
  )
  .execute();

这种方式会生成正确的 SQL 语法，避免了多余的括号问题。Kysely 的构建器 API 会正确处理部分唯一索引的条件表达式，生成符合 PostgreSQL 语法的冲突处理子句。

为什么直接使用 SQL 表达式有问题

直接使用 sql 标签插入原始表达式：

.onConflict(conflict => {
    conflict.expression(sql`(my_identifier) WHERE my_type = 'foo'`)
})

会导致 Kysely 添加额外的括号，生成如下错误语法：

ON CONFLICT ((my_identifier) WHERE my_type = 'foo')

这种语法在 PostgreSQL 中是不合法的，因为冲突规范不应该被额外的括号包围。

最佳实践

1. 尽量使用 Kysely 提供的构建器方法而不是原始 SQL
2. 对于部分唯一索引，使用 column() 和 where() 方法组合
3. 如果需要更复杂的条件，考虑使用 expression() 方法但要确保不引入额外括号

通过遵循这些实践，可以确保生成的 SQL 语句既符合 PostgreSQL 的语法要求，又能正确利用部分唯一索引的特性。