常见陷阱
默认值与 $default、timestamp 模式、SQLite 布尔、join 结果形状、迁移不可变等高频坑点与规避代码。
关于本页
官方 /docs/gotchas 目前仍是占位页(「will be a library of gotchas」)。以下条目整理自官方 column-types、joins、migrations、count-rows 与各驱动连接文档中明确记载的行为,并附规避代码。
default 与 $default 不是一回事
.default() 生成数据库端 DEFAULT 子句,进迁移文件;.$default() / .$defaultFn() 只在 Drizzle 运行时的 insert 中填充值,不影响 drizzle-kit,数据库里没有任何默认值。绕过 Drizzle 写入(原生 SQL、其他服务)时 $default 不生效。
export const users = pgTable('users', {
// 数据库默认:任何写入路径都生效
createdAt: timestamp().defaultNow(),
// 运行时默认:仅 Drizzle insert 生效,DDL 无 DEFAULT
id: text().$defaultFn(() => createId()),
}); 需要「更新时自动刷新」用 .$onUpdate(() => new Date()),同样是运行时行为。
timestamp 的 mode 与时区
timestamp({ mode: 'date' }) 推断为 Date,Drizzle 负责双向映射;mode: 'string' 原样透传字符串,不做任何转换。withTimezone: true 决定 timestamptz,存储值始终是 UTC。
export const events = pgTable('events', {
at: timestamp({ mode: 'date', withTimezone: true }), // Date
raw: timestamp({ mode: 'string' }), // string,自行解析
}); 坑点:timestamp without time zone 会静默忽略写入值携带的时区信息;跨时区业务一律用 withTimezone: true。
SQLite 没有原生 boolean
SQLite 的布尔要声明为 integer({ mode: 'boolean' }),Drizzle 在代码层映射 true/false,数据库存 0/1。直接写 SQL 查询时记得条件是 = 1 而不是 = true。
export const flags = sqliteTable('flags', {
enabled: integer({ mode: 'boolean' }).notNull().default(false),
// integer 还支持 timestamp / timestamp_ms 模式
seenAt: integer({ mode: 'timestamp' }),
}); join 结果是「平铺行」,不是嵌套对象
db.select().from(users).leftJoin(pets, ...) 返回按表名分组的平铺对象数组;left join 时从表可能整体为 null。一对多 join 会产生多行(用户重复出现),需要嵌套结构请用关系查询 db.query.users.findMany({ with: { posts: true } })。
const rows = await db.select().from(users)
.leftJoin(pets, eq(users.id, pets.ownerId));
// 类型:{ users: {...}; pets: {...} | null }[] PostgreSQL 的 count 与 bigint 返回字符串
count(*) 在 PG 中是 bigint,驱动按字符串返回。用 count() 辅助函数(运行时自动转 number),或 mapWith:
import { count, sql } from 'drizzle-orm';
await db.select({ n: count() }).from(users); // number
await db.select({ n: sql`count(*)`.mapWith(Number) }).from(users); bigint 列同理:bigint({ mode: 'number' }) 有精度风险,大整数用 mode: 'bigint'。numeric 默认也是字符串。
已应用的迁移不可变
迁移文件一旦在任何环境执行过,就不要再编辑、删除或重排——历史表按内容哈希/文件夹名记录,改动会导致校验失败或重复执行。写错了就生成一个新迁移去修正。
# 正确:追加修正迁移
npx drizzle-kit generate v1 的 drizzle-kit check 会检测跨分支冲突;删除已应用迁移可能迫使运行过它的数据库重置。
relations 声明不会创建外键
relations()(v1 的 defineRelations)只服务于关系查询,不产生任何 DDL。真正的引用完整性要靠列上的 .references():
export const posts = pgTable('posts', {
authorId: integer().notNull().references(() => users.id),
}); 只写 relations 不写 references,数据库不会阻止脏引用。
Neon HTTP 不支持交互式事务
drizzle-orm/neon-http 面向单条非交互查询;db.transaction 回调里「先查再决定写」的模式需要 WebSocket 驱动 drizzle-orm/neon-serverless,或改用 db.batch() 一次提交。详见 提供商页。
事务型连接池必须关闭预编译
postgres.js 经过 PgBouncer/Supabase/Appwrite 的 transaction 池模式时,prepared statements 会跨连接错乱:
const client = postgres(process.env.DATABASE_URL!, { prepare: false }); 直连或 session 模式则无需关闭。迁移与内省建议始终走直连。
D1 用 batch,不要指望交互式事务
Cloudflare D1 不支持交互式事务,多语句原子执行用 db.batch();Drizzle 的 D1 事务基于 batch,回调内读不到真实执行结果。每条查询还是一次网络往返,注意合并。
const [inserted] = await db.batch([
db.insert(users).values({ name: 'Dan' }).returning(),
db.update(counters).set({ n: sql`${counters.n} + 1` }),
]); insert/update 中 undefined 与 null 语义不同
.values() / .set() 里字段为 undefined 会被忽略(insert 时落到数据库默认值),null 才是显式写 NULL。想清空一列必须传 null;可选列的 TS 类型也据此区分。
push 适合原型,生产走迁移
drizzle-kit push 直接改库,可能产生删列/删表等数据丢失语句(v1 默认严格确认,--force 才会跳过)。生产环境用 generate + migrate,并审查 SQL;旧库接管时注意 schemaFilter,避免把未声明的表判定为删除,见 已有项目接入。