drizzle-orm

Drizzle ORM（1.0 RC）

此技能适用于 Drizzle 1.0 候选版本（drizzle-orm@rc，目前为 1.0.0-rc.4），以及 drizzle-kit、drizzle-seed、内置验证器、Studio 和官方 Effect 驱动。

对于新项目，不要将 npm latest（0.45.x / kit 0.31.x）视为当前版本。ORM、Kit 和 Seed 应一起固定到 rc 频道。稳定版 1.0.0 尚未发布；rc5 风格的 dist-tag 是提交预览，而非 RC 版本线。

工作流

1. 检查本地 Drizzle 环境：
   • drizzle-orm、drizzle-kit、drizzle-seed、eslint-plugin-drizzle 的确切版本 / dist-tag。
   • 方言和驱动入口（postgres-js、neon-http、bun-sql、libsql、effect-postgres 等）。
   • Schema 文件、defineRelations、drizzle.config.ts、迁移目录结构（v3 目录还是旧版 journal）。
   • 使用的是 Effect（effect 4.x + drizzle-orm/effect-*）还是 Promise 驱动。
2. 安装、日常使用、基线和故障排除请优先参阅 usage-guide.md。
3. 版本不一致或任务涉及 RQBv2、kit v3 迁移、codec 或 Effect 时，请更新文档。从 source-map.md 开始。
4. 深入了解相关内容：
   • Schema + SQL 查询构建器：schema-queries.md。
   • RQBv2 defineRelations / db.query：relations-rqb.md。
   • Kit CLI、配置、generate/migrate/push/pull/studio：kit-migrations.md。
   • Seed + Zod/Valibot/TypeBox/ArkType/Effect Schema：seed-validators.md。
   • Effect 驱动与 @effect/sql-drizzle 的对比：effect-integration.md。
   • 驱动矩阵 + 0.x → RC 升级：drivers-upgrade.md。
5. 除非用户要求切换，否则保留项目现有的方言和驱动。
6. 使用范围最小且有效的查询、bunx drizzle-kit check / generate --explain 风格的试运行，或针对一次性数据库的定向迁移进行验证。

核心判断

• 新的 Drizzle 1.0 项目始终安装 @rc：bun add drizzle-orm@rc 和 bun add -D drizzle-kit@rc。绝不要将 RC ORM 与 Kit 0.31.x 混用。
• RQBv1 已移除。 使用 defineRelations(schema, …)，并将 { relations } 传入 drizzle()；db.query 不要使用逐表的 relations() + { schema }。
• 联表 / 聚合优先使用 SQL 查询构建器；嵌套图优先使用 RQB。
• 大小写配置针对表（snakeCase.table / camelCase.table），而不是 drizzle({ casing })。
• 生产环境的 Schema 变更：generate → migrate。仅在本地原型开发时使用 push（先运行 --explain）。
• 离开 0.x 后，运行一次 bunx drizzle-kit up，将迁移目录转换为 v3（不再有 journal.json）。
• 验证器已内置：drizzle-orm/zod、…/valibot、…/typebox、…/arktype、…/effect-schema。使用 RC 时避免搭配独立的 [email protected]。
• RC 上的 Effect：使用 drizzle-orm/effect-* + Effect v4（effect 4.0 已在 latest 稳定发布，且与 @effect/sql-* 4.x 匹配）。effect@beta 标签现在指向旧的预发布版本——不要安装。不要将 RC 与 @effect/sql-drizzle 搭配（仅适用于 Effect v3 / drizzle <0.50）。
• Kit 的非交互式 / CI / Agent 运行：使用 --output json，并通过 --hints / --hints-file 传入重命名 / 数据丢失决策，而不要回答提示；代码中请调用 drizzle-kit/cli SDK。
• 优先使用 $inferSelect / $inferInsert（别名：InferSelectModel / InferInsertModel）。

验证

优先使用仓库自带的命令。对于有实际意义的 Drizzle RC 工作，覆盖相关子集：

• 对 schema、relations 和 client factory 进行类型检查。
• 使用真实或测试数据库，重点测试 insert/select/update/delete 或 db.query.*.findMany。
• 运行 bunx drizzle-kit generate，然后检查 SQL；在一次性数据库上运行 migrate；使用 check 检查分支冲突。
• Seed：仅在非生产数据库上运行 reset + seed。
• Effect 路径：提供 PgClient（或 dialect）层，并端到端运行一个 Effect 程序。
• 完成 0.x 升级后：确认 RQBv2 重写、casing builders、migrator folder v3，以及对 codec 敏感的列（arrays、timestamps、JSON）。

报告运行了哪些检查、未运行哪些检查，以及仍存在哪些 @rc 与 latest 假设。