SQL Insert
db.insert() 完整参考:单行与批量插入、默认值与 $default、returning 与 $returningId、onConflict 系列 upsert 与 MySQL onDuplicateKeyUpdate。
本页示例沿用快速开始中的 db 实例与 users、employees 等表。values() 中的所有值都会自动参数化,不存在 SQL 拼接注入风险。
基本插入与类型推导
import { db } from './db';
import { users } from './db/schema';
await db.insert(users).values({ name: 'Andrew' });
// insert into "users" ("name") values ($1)
// 插入类型由 schema 推导:必填列不可省略,有默认值的列可选
type NewUser = typeof users.$inferInsert;
async function insertUser(user: NewUser) {
return db.insert(users).values(user);
} 批量插入传数组,生成一条多 values 的 insert:
await db.insert(users).values([{ name: 'Andrew' }, { name: 'Dan' }]); 默认值与 sql 表达式
- 省略的列使用数据库端
default;schema 里.default(...)定义 SQL 默认值。 .$defaultFn()/.$default()在运行时由 Drizzle 生成值(如 cuid、uuid),适合自定义主键。- 值的位置也可以放
sql表达式。
import { sql } from 'drizzle-orm';
import { createId } from '@paralleldrive/cuid2';
// schema 中:id: text().primaryKey().$defaultFn(createId)
await db.insert(users).values({ name: 'Dan' }); // id 由 createId() 生成
await db.insert(users).values({ name: 'Dan', createdAt: sql`now()` }); 拿回插入结果
// 整行返回
await db.insert(users).values({ name: 'Dan' }).returning();
// 部分返回
await db.insert(users).values({ name: 'Dan' }).returning({ insertedId: users.id }); Upsert:onConflict 系列(PG / SQLite)
冲突时忽略或转为更新,target 指定冲突目标列(主键或唯一索引):
// 冲突则什么都不做;不传 target 表示任意唯一约束冲突都忽略
await db.insert(users).values({ id: 1, name: 'John' }).onConflictDoNothing();
await db.insert(users).values({ id: 1, name: 'John' }).onConflictDoNothing({ target: users.id });
// 冲突则更新(upsert)
await db.insert(users)
.values({ id: 1, name: 'Dan' })
.onConflictDoUpdate({ target: users.id, set: { name: 'John' } }); set 中用 sql`excluded.列名` 引用“本来要插入的新值”;复合唯一索引传数组:
import { sql } from 'drizzle-orm';
await db.insert(users)
.values({ id: 1, name: 'Dan' })
.onConflictDoUpdate({ target: users.id, set: { name: sql`excluded.name` } });
await db.insert(users)
.values({ firstName: 'John', lastName: 'Doe' })
.onConflictDoUpdate({ target: [users.firstName, users.lastName], set: { firstName: 'John1' } }); 两个可选 where 位置不同、语义不同:
| 选项 | 生成的 SQL | 用途 |
|---|---|---|
targetWhere | on conflict (col) where ... | 匹配部分索引(partial index) |
setWhere | do update set ... where ... | 满足条件才执行更新 |
await db.insert(users)
.values({ id: 1, name: 'John Doe' })
.onConflictDoUpdate({
target: users.id,
set: { name: sql`excluded.name` },
setWhere: sql`name <> 'John Doe'`, // 已有行名字不同才更新
}); Upsert:onDuplicateKeyUpdate(MySQL)
MySQL 用 ON DUPLICATE KEY UPDATE,不需要也不能指定 target——任意主键或唯一索引冲突都会触发更新:
import { sql } from 'drizzle-orm';
await db.insert(users)
.values({ id: 1, name: 'John' })
.onDuplicateKeyUpdate({ set: { name: 'John' } });
// MySQL 没有"冲突则忽略",把某列设为自身即可实现 no-op
await db.insert(users)
.values({ id: 1, name: 'John' })
.onDuplicateKeyUpdate({ set: { id: sql`id` } }); 方言差异速记
PG/SQLite:onConflictDoNothing / onConflictDoUpdate(需指定 target)。MySQL:onDuplicateKeyUpdate(无 target),忽略冲突用 set: { id: sql`id` } 技巧。跨方言代码不要混用这两组方法。
Insert into … select
把一个 select 的结果直接插入另一张表,三种方言语法一致(v1 新增):
import { eq } from 'drizzle-orm';
// 形式一:直接传查询
await db.insert(employees).select(
db.select({ id: users.id, name: users.name }).from(users).where(eq(users.role, 'employee')),
);
// 形式二:回调
await db.insert(employees).select(() =>
db.select({ id: users.id, name: users.name }).from(users).where(eq(users.role, 'employee')),
); 也可以传 (qb) => qb.select(...)(独立 QueryBuilder)或 sql 模板写的自定义 select。select 的列名需与目标表列对应。
常见坑
values([])空数组会报错,批量插入前先判空。- PG/SQLite 的
onConflictDoUpdate忘写target会报类型错误;MySQL 的onDuplicateKeyUpdate写了 target 反而不存在该选项。 - 需要“插入并读回 + 业务校验”的原子性时,包在事务里。