drizzle-orm

Drizzle ORM

概述

Drizzle ORM 是一款轻量、类型安全的 TypeScript ORM，可直接映射到 PostgreSQL、MySQL 和 SQLite 的 SQL。它提供类 SQL 查询构建器和关系查询 API，零依赖，并完全兼容无服务器环境。需要编译时类型安全和 SQL 级控制时，请使用 Drizzle；需要功能齐全、带自动迁移的 Active Record ORM 时（使用 Prisma），或使用 MongoDB/NoSQL 数据库时，请避免使用 Drizzle。

快速参考

模式	API	关键要点
Schema 定义	pgTable('name', { columns }, (t) => [indexes])	第三个参数返回索引/约束数组
列类型	text(), integer(), boolean(), timestamp()	从 drizzle-orm/pg-core 导入
类型推断	typeof table.$inferSelect, $inferInsert	直接从 Schema 推导 TS 类型
关系查询	db.query.table.findMany({ with, where })	要求将 Schema 传入 drizzle() 客户端
类 SQL 查询	db.select().from(table).where()	可链式调用，返回行数组
插入	db.insert(table).values({}).returning()	使用 .returning() 获取插入的行
更新	db.update(table).set({}).where().returning()	始终包含 .where()，以避免更新整张表
删除	db.delete(table).where()	始终包含 .where()，以避免删除整张表
Upsert	.onConflictDoUpdate({ target, set })	在 .insert().values() 后链式调用
事务	db.transaction(async (tx) => { ... })	抛出错误时自动回滚
筛选器	eq(), and(), or(), inArray(), sql\``	从 drizzle-orm 导入运算符
关系	relations(table, ({ one, many }) => ({}))	为关系查询声明逻辑关系
生成迁移	drizzle-kit generate	根据 Schema 差异创建 SQL 迁移文件
应用迁移	drizzle-kit migrate 或代码中的 migrate()	将待处理的迁移应用到数据库
推送 Schema	drizzle-kit push	直接推送 Schema，不生成迁移文件
预处理语句	db.select().from(t).where(eq(t.id, sql.placeholder('id'))).prepare()	可复用的参数化查询
视图	pgView('name').as(qb => ...)	普通视图和物化视图
$count 工具	db.$count(table, filter?)	计数简写，可用作子查询
生成列	text().generatedAlwaysAs(() => sql\...`)`	计算列（虚拟或存储）
检查约束	check('name', sql\condition`)`	在数据库层面进行行级验证

常见错误

错误	正确做法
插入/更新时缺少 .returning()	链接调用 .returning() 以获取插入/更新后的行
更新/删除时省略 .where()	始终提供 .where()，以避免影响所有行
查询结果类型使用 any	使用 $inferSelect / $inferInsert 获取类型安全的结果
未向 drizzle() 客户端传入 schema	传入 { schema } 以启用 db.query 关系 API
忘记在外键列上创建索引	为用于联接/查找的列添加显式索引
未在事务中包装相关写入	对多表变更使用 db.transaction()
使用 casing: 'snake_case' 时使用原始列名	使用大小写转换选项时，以 camelCase 定义列，不带名称参数
声明关系但遗漏反向关系	关系两端都需要声明，才能进行关系查询
在新的 PostgreSQL 架构中使用 serial()	优先使用 integer().generatedAlwaysAsIdentity()（现代做法）
未处理 findFirst 返回 undefined	访问属性前检查是否为 undefined
从错误的方言模块导入列类型	PostgreSQL 使用 drizzle-orm/pg-core，MySQL 使用 mysql-core，SQLite 使用 sqlite-core
使用 .references() 代替 relations()	.references() 用于 SQL 外键；relations() 用于查询 API

委派

如果有 tanstack-query skill，请将客户端缓存和服务端状态管理委派给它。 否则，建议使用：npx skills add oakoss/agent-skills --skill tanstack-query

如果有 tanstack-start skill，请将数据库访问的服务端函数模式委派给它。 否则，建议使用：npx skills add oakoss/agent-skills --skill tanstack-start

如果有 electricsql skill，请将 Electric 设置、shape 配置和写入模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y

如果有 pglite skill，请将 PGlite 专属配置、扩展和浏览器存储模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s pglite -a claude-code -y

• 架构验证：使用 drizzle-zod 从 Drizzle 表生成 Zod 架构以验证输入
• 查询模式探索：使用 Explore Agent
• 代码审查：委派给 code-reviewer Agent

参考资料

• 架构定义、列类型、约束、索引和类型推断
• 关系查询、类 SQL API、联接、子查询和聚合
• 插入、更新、删除、插入或更新以及事务
• 关系：一对一、一对多、带子句的嵌套关系、自引用
• 迁移：drizzle-kit generate、migrate、push、pull、studio
• 筛选运算符：eq、ne、gt、lt、like、inArray、sql 模板
• 视图、物化视图、生成列、检查约束、$count、批量 API
• ElectricSQL + PGlite 集成：驱动设置、架构到 shape 的映射、类型推断、本地同步