drizzle-orm-pg 0.14.3 深入解析:onConflict 冲突处理修复与 insert/update/delete returning 完整指南

原创2026-09-18 20:37:451,610 阅读
文章标签:ORM数据库关系型数据库数据存储CLI代码生成后端

drizzle-orm-pg 0.14.3 深入解析:onConflict 冲突处理修复与 insert/update/delete returning 完整指南

drizzle-orm-pg 0.14.3 是面向 PostgreSQL 的 ORM 方言包的一个补丁版本,核心修复了 .onConflict 语句构建器中冲突目标列(target column)的映射问题,并同步补充了 onConflict 与 insert/update/delete returning 的文档示例和测试用例。读完本文,你将掌握 drizzle-orm-pg 中 upsert(onConflictDoNothing / onConflictDoUpdate)与 returning 子句的完整用法、底层 SQL 生成原理,以及 0.14.3 修复的具体行为差异。

一、版本背景:0.14.3 修复了什么

根据 changelogs/drizzle-orm-pg/0.14.3.md,本次发布包含四项内容:

  • 修复 .onConflict 语句查询构建器:在之前的版本中,冲突目标列会连同表名一起被映射;
  • 为 onConflict 补充文档示例;
  • 为 insert/update/delete 的 returning 语句补充文档示例;
  • 为 onConflict 查询构建器增加更多测试。

其中最关键的是第一点。在旧版本中,当用户写出类似 onConflictDoUpdate({ target: usersTable.id, ... }) 的调用时,生成的 SQL 可能会把目标列错误地处理成带有表名前缀的形式;而 PostgreSQL 的 ON CONFLICT (col) 语法中目标列应只包含列名。0.14.3 修正了这一映射逻辑。

二、onConflict 的底层实现:修复点与 SQL 生成原理

2.1 修复后的列名映射逻辑

修复的核心位于 drizzle-orm/src/pg-core/query-builders/insert.ts 中的 PgInsertBase 类。无论是 onConflictDoNothing 还是 onConflictDoUpdate,现在都统一通过 this.dialect.escapeName(this.dialect.casing.getColumnCasing(it)) 来生成目标列名:

// onConflictDoNothing 内部(drizzle-orm/src/pg-core/query-builders/insert.ts#L326-L336)
if (config.target === undefined) {
	this.config.onConflict = sql`do nothing`;
} else {
	let targetColumn = '';
	targetColumn = Array.isArray(config.target)
		? config.target.map((it) => this.dialect.escapeName(this.dialect.casing.getColumnCasing(it))).join(',')
		: this.dialect.escapeName(this.dialect.casing.getColumnCasing(config.target));

	const whereSql = config.where ? sql` where ${config.where}` : undefined;
	this.config.onConflict = sql`(${sql.raw(targetColumn)})${whereSql} do nothing`;
}

从这段代码可以推断,修复后的行为是:

  • 只对列本身做命名转义(escapeName,输出带双引号的标识符),并应用当前方言的命名策略(getColumnCasing,如蛇形/驼峰转换);
  • 不再拼接表名,因此生成的目标列是 ("id") 而不是 ("users"."id");
  • 支持传入单个列或列数组(多列冲突目标)。

onConflictDoUpdate 使用完全相同的列名生成逻辑,见 drizzle-orm/src/pg-core/query-builders/insert.ts:

this.config.onConflict = sql`(${
	sql.raw(targetColumn)
})${targetWhereSql} do update set ${setSql}${whereSql}${setWhereSql}`;

2.2 最终 SQL 的组装

onConflict 片段最终由 PgDialect.buildInsertQuery 拼装进完整的 INSERT 语句,见 drizzle-orm/src/pg-core/dialect.ts:

const onConflictSql = onConflict ? sql` on conflict ${onConflict}` : undefined;

return sql`${withSql}insert into ${table} ${insertOrder} ${overridingSql}${valuesSql}${onConflictSql}${returningSql}`;

完整的语句形态为:

insert into "users" ("id", "name", ...) values (default, $1, ...) on conflict ("id") do update set "name" = $3 returning ...

也就是说,onConflictDoNothing / onConflictDoUpdate 内部构造的 SQL 片段会被直接嵌入 ON CONFLICT 之后,因此修复列名映射即可直接影响最终发送给 PostgreSQL 的语句。

三、upsert 完整用法:onConflictDoNothing 与 onConflictDoUpdate

3.1 onConflictDoNothing:冲突时放弃插入

onConflictDoNothing 用于在发生唯一性/主键冲突时跳过插入。它有两种调用形态(源码 JSDoc 与文档示例见 drizzle-orm/src/pg-core/query-builders/insert.ts):

// 不指定目标:任何冲突都跳过
await db.insert(cars)
	.values({ id: 1, brand: 'BMW' })
	.onConflictDoNothing();

// 显式指定冲突目标列
await db.insert(cars)
	.values({ id: 1, brand: 'BMW' })
	.onConflictDoNothing({ target: cars.id });

可选参数:

参数 类型 说明
target IndexColumn | IndexColumn[] 冲突检测的列(单个或数组),省略时对任意冲突生效
where SQL 可选的冲突判定条件,生成 ON CONFLICT (col) WHERE ... DO NOTHING

3.2 onConflictDoUpdate:冲突时更新(真正的 upsert)

onConflictDoUpdate 在冲突时执行 UPDATE,配置类型为 PgInsertOnConflictDoUpdateConfig(见 drizzle-orm/src/pg-core/query-builders/insert.ts):

export interface PgInsertOnConflictDoUpdateConfig<T extends AnyPgInsert> {
	target: IndexColumn | IndexColumn[];
	/** @deprecated use either `targetWhere` or `setWhere` */
	where?: SQL;
	targetWhere?: SQL;
	setWhere?: SQL;
	set: PgUpdateSetSource<T['_']['table']>;
}

基础用法:

await db.insert(cars)
	.values({ id: 1, brand: 'BMW' })
	.onConflictDoUpdate({
		target: cars.id,
		set: { brand: 'Porsche' },
	});

配合条件过滤的高级用法(文档示例见 drizzle-orm/src/pg-core/query-builders/insert.ts):

// 仅在目标行满足条件时才执行更新
await db.insert(cars)
	.values({ id: 1, brand: 'BMW' })
	.onConflictDoUpdate({
		target: cars.id,
		set: { brand: 'newBMW' },
		targetWhere: sql`${cars.createdAt} > '2023-01-01'::date`,
	});

关于 where 参数有一个重要约束(源码在 drizzle-orm/src/pg-core/query-builders/insert.ts 中做了显式校验):where 已被标记为 deprecated,推荐使用 targetWhere(限定 ON CONFLICT 的目标行)或 setWhere(限定 UPDATE SET 的生效范围);如果同时传入 where 与 targetWhere/setWhere,运行时会直接抛出错误:

if (config.where && (config.targetWhere || config.setWhere)) {
	throw new Error(
		'You cannot use both "where" and "targetWhere"/"setWhere" at the same time - "where" is deprecated, use "targetWhere" or "setWhere" instead.',
	);
}

3.3 生成的 SQL 与测试验证

onConflict 相关测试位于 integration-tests/tests/pg/pg-common.ts,包含构建查询与真实执行两类用例。以下是几个代表性断言:

// 单列 target 的 do update
// => '... on conflict ("id") do update set "name" = $3'
.onConflictDoUpdate({ target: usersTable.id, set: { name: 'John1' } })

// 多列 target
// => '... on conflict ("id","name") do update set "name" = $3'
.onConflictDoUpdate({ target: [usersTable.id, usersTable.name], set: { name: 'John1' } })

// 不带 target 的 do nothing
// => '... on conflict do nothing'
.onConflictDoNothing()

// 带 target 的 do nothing
// => '... on conflict ("id") do nothing'
.onConflictDoNothing({ target: usersTable.id })

注意生成 SQL 中目标列只有列名、没有表名前缀,这正是 0.14.3 修复点的直接体现。此外,0.14.3 还覆盖了带 schema 的表(mySchema :: ... 用例,见 integration-tests/tests/pg/pg-common.ts),说明在多 schema 场景下同样适用。

四、insert/update/delete 的 returning 语句

0.14.3 为三种写操作的 returning 补充了文档示例。returning 允许在写入后直接取回受影响的行,避免额外的 SELECT 查询。

4.1 insert + returning

PgInsertBase.returning 的签名与 JSDoc 示例(见 drizzle-orm/src/pg-core/query-builders/insert.ts):

// 不传字段:返回被插入行的所有列
const insertedCar: Car[] = await db.insert(cars)
	.values({ brand: 'BMW' })
	.returning();

// 指定字段:只返回 id
const insertedCarId: { id: number }[] = await db.insert(cars)
	.values({ brand: 'BMW' })
	.returning({ id: cars.id });

returning 还支持任意字段投影,包括经过 sql 表达式包装的计算列:

const res = await db.insert(users)
	.values({ age1: 1, class: 'A', enumCol: 'a', homeCity: 1, arrayCol: [] })
	.returning({
		id: users.id,
		homeCity: users.homeCity,
		subclassLower: sql`lower(${users.subClass})`,
		classLower: sql<string>`lower(${users.class})`,
	});

类型测试 drizzle-orm/type-tests/pg/insert.ts 对返回类型做了严格校验:.returning() 返回 typeof users.$inferSelect[],.returning({ id, homeCity, mySubclass }) 返回对应的结构化对象数组。

4.2 returning 与 onConflict 的组合

returning 与 onConflictDoUpdate 可以链式组合,实现"插入或更新后返回最终行数据"的完整 upsert 流程。动态构建时也允许在任意顺序组合,类型测试 drizzle-orm/type-tests/pg/insert.ts 中的用例:

function dynamic<T extends PgInsert>(qb: T) {
	return qb.returning().onConflictDoNothing().onConflictDoUpdate({ set: {}, target: users.id, where: sql`` });
}

不过需要注意方法调用的一次性约束:returning()、onConflictDoNothing() 等方法在调用后会从类型层面剔除(PgInsertWithout),重复调用会触发 TypeScript 编译错误(见 drizzle-orm/type-tests/pg/insert.ts 中的 @ts-expect-error 用例)。

4.3 update/delete + returning

update 与 delete 构建器同样支持 returning。drizzle-orm-pg 中三种写操作共享同一套字段投影与类型推导机制(orderSelectedFields 排序后进入 buildSelection,见 drizzle-orm/src/pg-core/dialect.ts),使用方式与 insert 完全一致:

// update 后返回更新行
const updated = await db.update(usersTable)
	.set({ name: 'John1' })
	.where(eq(usersTable.id, 1))
	.returning();

// delete 后返回被删除行(部分字段)
const removed = await db.delete(usersTable)
	.where(eq(usersTable.id, 1))
	.returning({ id: usersTable.id });

returning 字段的排序由 orderSelectedFields 处理,确保与 SELECT 查询的字段顺序规则一致;未指定字段时默认返回整行(returning(fields = this.config.table[Table.Symbol.Columns]))。

五、命名策略(casing)与 onConflict 的协同

由于 0.14.3 的修复改为通过 getColumnCasing 处理目标列,onConflict 与表的命名映射策略(如 snake_case / camelCase)可以正确协同。相关回归测试见 drizzle-orm/tests/casing/pg-to-camel.test.ts:

await db.insert(users)
	.values({ ... })
	.onConflictDoNothing({ target: users.first_name });   // 生成 on conflict ("firstName") do nothing

await db.insert(users)
	.values({ ... })
	.onConflictDoUpdate({ target: users.first_name, set: { age: 31 } });

在驼峰命名策略下,传入 users.first_name 会生成 ON CONFLICT ("firstName"),目标列只做列名级转换、不引入表名,这从侧面印证了 0.14.3 修复后的行为符合 PostgreSQL 语法要求,也说明该修复对开启了自定义 casing 的项目同样生效。

六、如何升级与验证

  • 升级方式:在项目中将 drizzle-orm-pg 依赖升级到 0.14.3(该版本包与 drizzle-orm 主包配合使用,需保证主包版本兼容)。
  • 验证点:升级后重点回归以下场景——
    1. onConflictDoUpdate / onConflictDoNothing 生成的目标列不含表名前缀;
    2. 多列 target、带 targetWhere / setWhere 的 upsert 行为正常;
    3. insert/update/delete 的 returning 字段投影与返回类型推导不受影响;
    4. 开启了 snake_case / camelCase 等命名策略的项目,冲突目标列转换正确。

仓库中的集成测试(integration-tests/tests/pg/pg-common.ts)、类型测试(drizzle-orm/type-tests/pg/insert.ts)与 casing 测试(drizzle-orm/tests/casing)共同构成了该版本行为的验证矩阵,可作为升级回归的参考基线。

七、小结

drizzle-orm-pg 0.14.3 虽然只是一个补丁版本,但其修复切中了 PostgreSQL ON CONFLICT 语法的一个关键细节:冲突目标列必须只包含列名。修复后,onConflictDoNothing 与 onConflictDoUpdate 在单列、多列、条件过滤、自定义命名策略等场景下都能生成正确的 SQL;配套补充的 returning 文档示例则让"写入即返回"这一高频模式在 insert/update/delete 三类操作中的用法更加清晰。掌握本文介绍的 API 形态与 SQL 生成原理,即可在项目中安全、高效地使用 drizzle-orm-pg 的 upsert 与 returning 能力。

登录后查看全文
drizzle-orm