drizzle-orm-patterns

Drizzle ORM 模式

概述

使用 Drizzle ORM 构建类型安全数据库应用的专家指南。涵盖所有受支持数据库的架构定义、关系、查询、事务和迁移。

适用场景

• 使用表、列和约束定义数据库架构
• 创建表之间的关系（一对一、一对多、多对多）
• 编写类型安全的 CRUD 查询
• 实现复杂的联接和聚合
• 管理数据库事务并支持回滚
• 使用 Drizzle Kit 设置迁移
• 使用 PostgreSQL、MySQL、SQLite、MSSQL 或 CockroachDB

快速参考

数据库	表函数	导入路径
PostgreSQL	pgTable()	drizzle-orm/pg-core
MySQL	mysqlTable()	drizzle-orm/mysql-core
SQLite	sqliteTable()	drizzle-orm/sqlite-core
MSSQL	mssqlTable()	drizzle-orm/mssql-core

操作	方法	示例
插入	db.insert()	db.insert(users).values({...})
查询	db.select()	db.select().from(users).where(eq(...))
更新	db.update()	db.update(users).set({...}).where(...)
删除	db.delete()	db.delete(users).where(...)
事务	db.transaction()	db.transaction(async (tx) => {...})

操作说明

1. 确定数据库方言 - 选择 PostgreSQL、MySQL、SQLite、MSSQL 或 CockroachDB
2. 定义架构 - 使用相应的表函数（pgTable、mysqlTable 等）
3. 设置关系 - 使用 relations() 或 defineRelations() 定义关系
4. 初始化数据库客户端 - 使用正确的凭据创建 Drizzle 客户端
5. 编写查询 - 使用查询构建器执行类型安全的 CRUD 操作
6. 处理事务 - 在需要时将多步操作封装在事务中
7. 设置迁移 - 配置 Drizzle Kit 以管理架构

示例

示例 1：基本架构和查询

import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import { drizzle } from 'drizzle-orm/node-postgres';
import { eq } from 'drizzle-orm';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
});

const db = drizzle(process.env.DATABASE_URL);

const [user] = await db.select().from(users).where(eq(users.id, 1));

示例 2：CRUD 操作

import { eq } from 'drizzle-orm';

// Insert
const [newUser] = await db.insert(users).values({
  name: 'John',
  email: '[email protected]',
}).returning();

// Update
await db.update(users)
  .set({ name: 'John Updated' })
  .where(eq(users.id, 1));

// Delete
await db.delete(users).where(eq(users.id, 1));

示例 3：带回滚的事务

await db.transaction(async (tx) => {
  const [from] = await tx.select().from(accounts)
    .where(eq(accounts.userId, fromId));

  if (from.balance < amount) {
    tx.rollback();
  }

  await tx.update(accounts)
    .set({ balance: sql`${accounts.balance} - ${amount}` })
    .where(eq(accounts.userId, fromId));
});

高级事务模式请参阅 references/transactions.md。

最佳实践

1. 类型安全：始终使用 TypeScript，并利用 $inferInsert / $inferSelect
2. 关系：使用 relations() API 定义关系，以支持嵌套查询
3. 事务：对于必须共同成功的多步操作，使用事务
4. 迁移：生产环境使用 generate + migrate，开发环境使用 push
5. 索引：在经常查询的列和外键上添加索引
6. 软删除：尽可能使用 deletedAt 时间戳，而非硬删除
7. 分页：对大型数据集使用基于游标的分页
8. 查询优化：使用 .limit() 和 .where() 仅获取所需数据

约束和警告

• 外键约束：始终使用箭头函数 () => table.column 定义引用，以避免循环依赖问题
• 事务回滚：调用 tx.rollback() 会抛出异常 - 必要时使用 try/catch
• Returning 子句：并非所有数据库都支持 .returning() - 请检查方言兼容性
• 批量操作：大批量插入可能触及数据库限制 - 请拆分为较小的批次
• 生产环境迁移：应用迁移到生产环境之前，务必先在预发布环境中测试

参考资料

核心概念

• references/schema-definition.md - 所有数据库（PostgreSQL、MySQL、SQLite）的完整架构定义、列类型、索引和约束
• references/relations.md - 使用 v1 和 v2 语法定义一对一、一对多、多对多关系
• references/queries-joins-aggregations.md - CRUD 操作、查询运算符、联接、聚合和分页

高级主题

• references/transactions.md - 事务模式、回滚处理、嵌套事务
• references/migrations.md - Drizzle Kit 配置、CLI 命令、迁移工作流
• references/common-patterns.md - 软删除、插入或更新、批量操作、全文搜索、审计追踪