drizzle-orm

Drizzle ORM 开发指南

本技能提供了在此项目中使用 Drizzle ORM 的指南、模式和最佳实践。

快速开始

如需详细的开发指南、模式和代码示例，请参阅 references/patterns.md。

核心理念

• 默认类型安全：利用 TypeScript 和 Drizzle 的类型推断，在编译时捕获数据库错误
• 性能优先：使用预处理语句和查询优化技术
• SQL 透明性：保持 SQL 查询易于阅读，避免过度抽象
• 最小开销：Drizzle 是一个轻量层——应合理使用，避免不必要的复杂性

常见任务

模式定义

按领域将模式组织到单独的文件中。使用流畅的约束链式调用，并为频繁查询的列添加索引。

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

类型导出

始终导出表类型，以供应用程序使用：

export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

预处理语句

对频繁执行的查询使用预处理语句，以获得显著的性能提升：

export const getUserById = db
  .select()
  .from(users)
  .where(eq(users.id, sql.placeholder('id')))
  .prepare();

// Usage
const user = await getUserById.execute({ id: userId });

事务

对多步骤操作使用事务，以保持数据一致性：

return db.transaction(async (tx) => {
  const [user] = await tx.insert(users).values(userData).returning();
  const [profile] = await tx.insert(profiles).values({ userId: user.id, ...profileData }).returning();
  return { user, profile };
});

迁移命令

重要：迁移时始终使用包脚本。切勿直接调用 drizzle-kit。

• 后端：pnpm run db:generate（生成迁移）
• 后端：pnpm run db:migrate（应用迁移）
• Landing：pnpm run db:generate（生成迁移）
• Landing：pnpm run db:migrate（应用迁移）

代码组织

db/
  index.ts           (Drizzle client initialization)
  schema/
    users.ts         (User table & relations)
    posts.ts         (Post table & relations)
  queries/
    users.ts         (User query functions)
    posts.ts         (Post query functions)
  migrations/        (Auto-generated migration files)

应避免的常见问题

1. 缺少索引：始终为 WHERE、JOIN 和 ORDER BY 子句中使用的列添加索引
2. 查询无界：面向用户的查询始终使用 limit() 和 offset()
3. 不安全的原始 SQL：切勿将用户输入拼接到原始 SQL 中——应使用 sql.placeholder()
4. N+1 查询：使用 with() 进行预加载，或执行批量查询
5. 缺少事务：将多步骤操作封装在事务中

验证清单

完成涉及 Drizzle ORM 的任务前：

• 检查模式定义是否为查询的列设置了适当的索引
• 确认重复查询使用了预处理语句
• 确保多步骤操作由事务封装
• 使用包脚本进行迁移（切勿直接调用 drizzle-kit）
• 运行类型检查（pnpm run typecheck）和测试（pnpm run test）

如需详细规则和代码示例，请参阅 references/patterns.md。