drizzle-best-practices

Drizzle ORM（PostgreSQL）最佳实践

Drizzle ORM 与 PostgreSQL 的全面最佳实践指南。内容涵盖 8 个类别，并按影响程度排序，帮助你编写正确、高性能且易于维护的数据库代码。

版本与 API 检测（请先阅读）

Drizzle 正处于向 v1 过渡的阶段，两个主要版本系列的关系 API 和关系查询 API 存在差异。编写代码前，请先检查项目的 package.json，以确保使用正确的语法：

已安装的 drizzle-orm	使用的 API	安装命令
^1.0.0-rc 或 ^1.0.0-beta	v1 — 本指南默认使用的版本。 defineRelations、对象语法关系查询（where: { … }、orderBy: { … }）、来自 drizzle-orm/zod 的验证器	npm i drizzle-orm@rc + npm i -D drizzle-kit@rc
^0.4x（例如 0.45.2）	旧版。 relations() 辅助函数、回调／运算符关系查询、来自独立 drizzle-zod 包的验证器	npm i drizzle-orm（解析为 0.45.2）

当前的候选发布版本是 [email protected]（@rc 标签），它取代了文档中仍有部分地方提及的旧 @beta 标签。

以下三点经常让 Agent 出错：

• @latest 仍然是 0.45.2，并非 v1。 npm i drizzle-orm 不会安装 v1——需要使用 v1 API 的新项目必须明确指定 @rc。
• 类 SQL 查询构建器在各版本间没有变化。 db.select().from(t).where(eq(t.id, 1))、db.insert()、db.update()、db.delete() 在 0.45.x 和 v1 中的用法完全相同。只有关系查询 API（db.query）和关系定义发生了变化。切勿将 db.select() 的运算符筛选重写为关系对象语法。
• 在 v1 中，关系查询 API（db.query）由 defineRelations 驱动。 传入旧版 schema 不会填充 db.query。为使现有关系模块在迁移期间仍能编译，旧版 relations() 辅助函数仍可从 drizzle-orm/_relations 导入；但要在 v1 中进行关系查询，必须将其转换为 defineRelations。（早期 beta 版本提供过 db._query 路径；该路径在 1.0.0-rc.3 之前已移除。）请参阅 references/relations-defining.md。

如果未注明版本，新代码默认使用 v1（RC）；但如果已看到代码库中使用旧版 relations()／回调式 db.query 模式，请遵循现有代码库所用的 API。在参考文件中，特定版本的差异会以 “Legacy (v0.45.x)” 提示标注。

适用场景

在以下场景中，请参考这些指南：

• 使用 pgTable 定义表结构
• 编写查询、插入、更新或删除语句
• 使用 defineRelations 或旧版 relations API 设置表间关系
• 配置 drizzle-kit 以执行迁移（generate、push、pull）
• 从架构推断 TypeScript 类型
• 在类 SQL API 和关系查询 API 之间进行选择
• 使用预处理语句或批量操作优化查询性能
• 将 Drizzle 集成到无服务器 Postgres 提供商（Neon、Supabase 等）

按优先级划分的规则类别

优先级	类别	影响	前缀
1	架构设计	关键	schema-
2	查询模式	关键	query-
3	关系	高	relations-
4	迁移	高	migrations-
5	类型安全	中高	types-
6	性能	中	perf-
7	数据库驱动程序	中	driver-
8	高级模式	低	advanced-

使用方法

阅读各个参考文件，查看详细说明和代码示例：

references/engine-postgres.md          # Postgres-specific types, features, and patterns
references/schema-table-definitions.md
references/query-select-patterns.md
references/relations-defining.md
references/_sections.md                # Full index of all references

每个参考文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• Drizzle 官方文档链接

References

• https://orm.drizzle.team/docs/overview
• https://orm.drizzle.team/docs/sql-schema-declaration
• https://orm.drizzle.team/docs/relations-v2
• https://orm.drizzle.team/docs/perf-queries
• https://orm.drizzle.team/docs/kit-overview
• https://orm.drizzle.team/llms.txt