Drizzle ORM 中 SQLite 复合主键与唯一约束的冲突处理问题解析

在使用 Drizzle ORM 操作 SQLite 数据库时，开发者经常会遇到复合主键和唯一约束下的冲突处理问题。本文将以一个典型的 genres 关联表为例，深入分析 onConflictDoUpdate 方法在复合键场景下的正确用法。

问题背景

在影视音乐管理系统中，通常会设计一个 genres_join 关联表来建立作品与类型之间的多对多关系。这个表需要处理多种实体（电影、电视剧、艺术家、专辑）与类型的关联，因此设计了一个包含五个字段的复合主键。

初始表结构设计

export const genresJoinTable = sqliteTable(
  'genres_join',
  {
    movieId: integer('movie_id').references(() => moviesTable.id),
    tvShowId: integer('tv_show_id').references(() => tvShowsTable.id),
    artistId: integer('artist_id').references(() => artistsTable.id),
    albumId: integer('album_id').references(() => albumsTable.id),
    genreId: integer('genre_id')
      .notNull()
      .references(() => genresTable.id),
  },
  (t) => ({
    pk: primaryKey({
      columns: [t.movieId, t.tvShowId, t.artistId, t.albumId, t.genreId],
    }),
  }),
);

问题现象

开发者尝试使用 onConflictDoUpdate 方法来处理电视剧与类型关联的重复插入问题：

await tx
  .insert(genresJoinTable)
  .values({ genreId: genre.id, tvShowId: insertedTvShow[0].id })
  .onConflictDoUpdate({
    target: [genresJoinTable.genreId, genresJoinTable.tvShowId],
    set: {
      genreId: sql`excluded.genre_id`,
      tvShowId: sql`excluded.tv_show_id`,
    },
  })

但发现该方法并未按预期工作，系统仍然会插入重复的记录。

问题根源分析

1. 复合主键与冲突目标的误解：开发者试图仅针对 genreId 和 tvShowId 两个字段设置冲突处理，但这两个字段只是五字段复合主键的一部分，SQLite 无法仅基于部分主键字段判断冲突。

2. 唯一约束的缺失：要实现针对特定字段组合的冲突处理，必须为这些字段组合显式定义唯一约束，而不能依赖复合主键。

解决方案

方案一：重构表结构

最佳实践是为每种关联类型创建单独的唯一约束：

export const genresJoinTable = sqliteTable(
  'genres_join',
  {
    id: integer('id').primaryKey(),
    movieId: integer('movie_id').references(() => moviesTable.id),
    tvShowId: integer('tv_show_id').references(() => tvShowsTable.id),
    genreId: integer('genre_id').notNull().references(() => genresTable.id),
  },
  (t) => ({
    movieGenreUnq: unique('movie_genre').on(t.movieId, t.genreId),
    tvShowGenreUnq: unique('tv_show_genre').on(t.tvShowId, t.genreId),
  })
);

方案二：正确使用冲突目标

如果保持原表结构，必须为需要冲突检测的字段组合创建单独的唯一约束：

// 在表定义中添加
unq: unique().on(t.genreId, t.tvShowId)

// 然后在操作中指定正确的冲突目标
.onConflictDoUpdate({
  target: [genresJoinTable.genreId, genresJoinTable.tvShowId],
  set: {
    genreId: sql`excluded.genre_id`,
    tvShowId: sql`excluded.tv_show_id`,
  },
})

实践建议

1. 避免过大的复合主键：当复合主键包含太多字段时，考虑使用自增ID作为主键，再为业务需要的字段组合创建唯一约束。

2. 明确业务约束：仔细分析业务场景，只为真正需要唯一性的字段组合创建约束。

3. 考虑使用 onConflictDoNothing：如果冲突时不需要更新数据，使用这个更简单的方法性能更好。

4. 测试边界情况：特别测试空值情况，因为NULL值在唯一约束中的处理方式可能出乎意料。

通过正确理解Drizzle ORM的冲突处理机制和SQLite的约束特性，开发者可以构建出更健壮的数据持久层，有效避免重复数据问题。