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';

// 插入
const [newUser] = await db.insert(users).values({
  name: 'John',
  email: 'john@example.com',
}).returning();

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

// 删除
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() - 请检查您的方言兼容性
• 批量操作：大批量插入可能达到数据库限制 - 分批次处理
• 生产环境迁移：在应用到生产环境之前，始终在预发布环境中测试迁移

参考资料

核心概念

• 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 - 软删除、upsert、批量操作、全文搜索、审计日志