tech-drizzle

Drizzle ORM 类型安全的数据库访问

轻量、无头的 TypeScript ORM，零依赖。Drizzle 擅长：

• 类型推断 — 从架构中获取完整的 TypeScript 类型；无需生成类型或使用单独的架构语言
• 关系查询 — 使用 .with() 获取嵌套数据，无需手动联接
• 预处理语句 — 预编译查询以便重复执行；显著提升性能
• 迁移 — 使用 drizzle-kit 对架构变更进行版本控制；支持回滚
• 事务 — 原子性提交多项操作，并通过保存点支持嵌套事务

核心模式：每个文件一个表、使用关系 API 进行嵌套查询、对热点路径使用预处理语句、使用事务确保一致性。

工作流

使用 Drizzle ORM 时：

1. 设计架构 — 表、列、约束；每个文件一个表
2. 定义关系 — 使用 defineRelations() 定义一对多、多对多关系；支持嵌套查询
3. 选择查询风格 — 嵌套数据优先使用关系 API，也可使用 SQL 构建器以获得灵活性
4. 优化热点路径 — 对重复查询使用带占位符的预处理语句
5. 处理事务 — 使用 db.transaction() 包裹多项写入操作
6. 测试迁移 — 推送前运行 drizzle-kit migrate:dev；检查生成的 SQL
7. 提取类型 — 使用 InferSelectModel 从架构中获取运行时类型

规则

模式按关注点分类：

• 架构 — 表设计、列类型、约束、每个文件一个表
• 关系查询 — 使用 with() 获取嵌套数据、部分列和筛选数据
• 查询构建器 — 使用 SQL 构建器进行聚合和复杂查询
• 预处理语句 — 预编译以提升性能；使用占位符传递参数
• 迁移 — 版本控制、检查 SQL、推送与生成
• 事务 — 原子操作、保存点、错误处理

请参阅 rules/，了解实现模式和示例。

示例

正向触发

用户：“为订单定义一个 Drizzle 架构，并建立与用户和产品的关系。”

预期行为：使用 tech-drizzle 指南，应用架构设计、关系查询和类型推断。

非触发

用户：“编写一条原始 SQL 迁移，为 users 表添加一列。”

预期行为：不要优先使用 tech-drizzle；选择更相关的技能，或不使用技能直接处理。

• 错误：在紧密循环中运行未经预处理的查询

• 原因：每次执行都会编译查询；没有复用已解析的 SQL

• 解决方案：使用带占位符的 .prepare()；使用不同参数多次执行

• 错误：在代码中手动联接；先获取父项，再单独获取子项

• 原因：未使用关系 API；编写了复杂的联接逻辑

• 解决方案：定义关系，使用 .with() 在单个查询中获取嵌套数据

故障排除

• 错误：从关系中选择数据时出现 Column not included in result

• 原因：选择嵌套关系时未显式包含列

• 解决方案：使用 columns: { id: true, name: true } 指定嵌套关系的列

• 错误：事务意外回滚；没有明确错误信息

• 原因：db.transaction() 内存在未处理的 Promise 拒绝

• 解决方案：使用 try/catch 包裹事务操作；必须捕获所有错误

• 错误：迁移后架构类型未更新

• 原因：drizzle-kit 未重新生成类型；缓存已过期

• 解决方案：架构变更后运行 drizzle-kit generate