Drizzle ORM 实战指南：为什么它正在取代 Prisma 成为 TypeScript 首选 ORM

选 ORM 这件事，TypeScript 社区吵了五年。Prisma 靠 DX（开发者体验）赢了前半场，但它的查询引擎二进制文件、N+1 查询黑盒、以及每次 prisma generate 都要等几秒的痛点，让越来越多团队在 2025-2026 年转向了 Drizzle ORM。npm 周下载量从 2024 年的 30 万飙升到 2026 年的 280 万，Vercel、Turso、Neon 官方文档都把 Drizzle 列为推荐方案。这篇文章不是入门教程，而是一份基于真实项目经验的深度分析——Drizzle 到底好在哪，什么场景不该用，以及从 Prisma 迁移过来的真实代价。

🔧 一、Drizzle ORM 核心设计哲学

1.1 SQL-First vs Schema-First：两条路线的根本分歧

Prisma 的核心理念是 Schema-First：你用 .prisma 文件定义数据模型，Prisma 生成 TypeScript 类型和查询引擎。这个设计的初衷是降低门槛——你不需要懂 SQL 也能写查询。但代价是：你无法控制生成的 SQL。

Drizzle 走了完全相反的路：SQL-First。它的 API 设计目标是让你写的 TypeScript 代码和生成的 SQL 之间有近乎 1:1 的映射关系。这意味着你对最终执行的查询有完全的控制权。

// Drizzle 的查询几乎就是 SQL 的 TypeScript 表达
// 生成的 SQL: SELECT id, name, email FROM users WHERE email = 'alice@example.com' LIMIT 1
const user = await db
  .select({ id: users.id, name: users.name, email: users.email })
  .from(users)
  .where(eq(users.email, 'alice@example.com'))
  .limit(1);

// Prisma 的查询是抽象的，你不知道底层 SQL 是什么
// 它可能是一条 SELECT *，也可能带了你没要求的 include
const user = await prisma.user.findUnique({
  where: { email: 'alice@example.com' },
  select: { id: true, name: true, email: true }
});

⚡ 关键结论： 如果你的团队有 SQL 基础，Drizzle 的 SQL-First 方式让你在调试慢查询时可以直接对应到代码。Prisma 的抽象在简单场景省心，但在复杂查询场景下反而成了障碍。

1.2 零运行时依赖 vs 查询引擎二进制

这是很多人选择 Drizzle 的直接原因。Prisma 的 @prisma/client 包含一个用 Rust 编写的查询引擎二进制文件（engine-core），在不同平台上需要不同的二进制。这导致了几个实际问题：

💡 提示： 如果你在 Vercel Edge Functions 或 Cloudflare Workers 上部署，Drizzle 的零二进制特性是决定性优势。Prisma 虽然有了 @prisma/adapter-pg 等方案，但配置复杂度显著增加。

1.3 Drizzle 的类型推断魔法

Drizzle 最被低估的能力是它的类型推断。它不需要代码生成步骤——所有类型都是从 Schema 定义中静态推断出来的。

// 定义 Schema 时，类型自动推断
import { pgTable, text, integer, timestamp, boolean } from 'drizzle-orm/pg-core';

export const posts = pgTable('posts', {
  id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
  title: text('title').notNull(),
  slug: text('slug').notNull().unique(),
  content: text('content'),
  viewCount: integer('view_count').default(0).notNull(),
  published: boolean('published').default(false).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

// select 的返回类型完全自动推断，不需要任何类型注解
const result = await db.select().from(posts);
// result 的类型: { id: number; title: string; slug: string; content: string | null; ... }[]

// 选择特定字段时，类型也会精确推断
const titles = await db.select({ title: posts.title }).from(posts);
// titles 的类型: { title: string }[]

这个设计的核心优势是零维护成本——修改 Schema 后，所有相关查询的类型自动更新，不需要重新运行 prisma generate。

🚀 二、实战：从零搭建 Drizzle 项目

2.1 项目初始化与 Schema 设计

我们以一个博客系统为例，展示 Drizzle 的完整用法。这个例子包含一对多关系、多对多关系、以及索引定义：

# 初始化项目
mkdir blog-drizzle && cd blog-drizzle
npm init -y
npm install drizzle-orm postgres
npm install -D drizzle-kit typescript @types/node

# 创建 drizzle 配置
cat > drizzle.config.ts << 'EOF'
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
  schema: './src/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});
EOF

// src/db/schema.ts — 完整的博客系统 Schema
import {
  pgTable, text, integer, timestamp, boolean,
  index, primaryKey, uuid
} from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

// ========== 用户表 ==========
export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  avatarUrl: text('avatar_url'),
  bio: text('bio'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
}, (table) => [
  index('users_email_idx').on(table.email),
]);

// ========== 文章表 ==========
export const posts = pgTable('posts', {
  id: uuid('id').primaryKey().defaultRandom(),
  title: text('title').notNull(),
  slug: text('slug').notNull().unique(),
  content: text('content'),
  excerpt: text('excerpt'),
  authorId: uuid('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  published: boolean('published').default(false).notNull(),
  viewCount: integer('view_count').default(0).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
}, (table) => [
  index('posts_author_idx').on(table.authorId),
  index('posts_slug_idx').on(table.slug),
  index('posts_published_idx').on(table.published, table.createdAt),
]);

// ========== 标签表 ==========
export const tags = pgTable('tags', {
  id: uuid('id').primaryKey().defaultRandom(),
  name: text('name').notNull().unique(),
  slug: text('slug').notNull().unique(),
});

// ========== 文章-标签关联表（多对多）==========
export const postTags = pgTable('post_tags', {
  postId: uuid('post_id').notNull().references(() => posts.id, { onDelete: 'cascade' }),
  tagId: uuid('tag_id').notNull().references(() => tags.id, { onDelete: 'cascade' }),
}, (table) => [
  primaryKey({ columns: [table.postId, table.tagId] }),
]);

// ========== 关系定义（用于关联查询）==========
export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one, many }) => ({
  author: one(users, { fields: [posts.authorId], references: [users.id] }),
  postTags: many(postTags),
}));

export const tagsRelations = relations(tags, ({ many }) => ({
  postTags: many(postTags),
}));

export const postTagsRelations = relations(postTags, ({ one }) => ({
  post: one(posts, { fields: [postTags.postId], references: [posts.id] }),
  tag: one(tags, { fields: [postTags.tagId], references: [tags.id] }),
}));

📌 记住： Drizzle 的 relations() 是纯 TypeScript 函数，不参与 SQL 迁移。它只在使用 db.query API 做关联查询时才生效。如果你用 db.select() + leftJoin() 写原生 SQL 关联，不需要定义 relations。

2.2 关联查询：db.query vs db.select

Drizzle 提供两种关联查询方式，适用场景完全不同：

// ===== 方式一：db.query — 声明式，适合简单关联 =====
// 自动生成嵌套 SQL 查询，返回嵌套对象
const postsWithAuthors = await db.query.posts.findMany({
  with: {
    author: true,  // 一对一关联
    postTags: {
      with: {
        tag: true,  // 嵌套关联：文章 → 关联表 → 标签
      },
    },
  },
  where: eq(posts.published, true),
  orderBy: (posts, { desc }) => [desc(posts.createdAt)],
  limit: 10,
});
// 返回结构: [{ title: "...", author: { name: "..." }, postTags: [{ tag: { name: "..." } }] }]

// ===== 方式二：db.select — 命令式，适合复杂查询 =====
// 完全控制 SQL，适合需要聚合、子查询、窗口函数的场景
const topPosts = await db
  .select({
    title: posts.title,
    viewCount: posts.viewCount,
    authorName: users.name,
    tagCount: sql<number>`count(distinct ${postTags.tagId})::int`,
  })
  .from(posts)
  .leftJoin(users, eq(posts.authorId, users.id))
  .leftJoin(postTags, eq(posts.id, postTags.postId))
  .where(eq(posts.published, true))
  .groupBy(posts.id, posts.title, posts.viewCount, users.name)
  .orderBy(desc(posts.viewCount))
  .limit(10);

💡 提示： db.query 的底层是多次查询（类似 Prisma 的 include），不是 JOIN。对于一对多关系，它会为每个关联发一条独立查询。如果你需要精确控制查询次数和性能，用 db.select() + leftJoin() 自己写。

2.3 数据库迁移实战

Drizzle Kit 的迁移系统比 Prisma 更透明——它通过对比 Schema 定义和数据库实际状态来生成纯 SQL 迁移文件：

# 生成迁移文件（对比 schema 和数据库，输出 SQL）
npx drizzle-kit generate

# 执行迁移
npx drizzle-kit migrate

# 直接推送 Schema 到数据库（开发环境，跳过迁移文件）
npx drizzle-kit push

# 打开 Drizzle Studio（可视化浏览数据）
npx drizzle-kit studio

// src/db/index.ts — 数据库连接
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client, { schema });

// 使用方式
import { db } from './db';
const allPosts = await db.select().from(posts);

⚠️ 警告： drizzle-kit push 会直接修改数据库结构，不会生成迁移文件。这意味着你无法追踪历史变更，也无法在多个环境间精确复现。开发环境可以用，但生产环境必须用 generate + migrate 流程。

💡 三、Drizzle vs Prisma：真实项目迁移指南

3.1 什么时候该用 Drizzle，什么时候不该

这取决于你的团队和项目特点：

3.2 从 Prisma 迁移的实战步骤

迁移不是简单的 API 替换，需要考虑数据类型映射、关系定义差异、以及查询模式的变化。以下是一个真实项目的迁移过程：

// ===== Prisma Schema（prisma/schema.prisma）=====
// model User {
//   id        String   @id @default(uuid())
//   email     String   @unique
//   name      String
//   posts     Post[]
//   createdAt DateTime @default(now())
// }
//
// model Post {
//   id        String   @id @default(uuid())
//   title     String
//   content   String?
//   author    User     @relation(fields: [authorId], references: [id])
//   authorId  String
//   createdAt DateTime @default(now())
// }

// ===== Drizzle Schema（迁移后的写法）=====
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

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

export const posts = pgTable('posts', {
  id: uuid('id').primaryKey().defaultRandom(),
  title: text('title').notNull(),
  content: text('content'),
  authorId: uuid('author_id').notNull().references(() => users.id),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, { fields: [posts.authorId], references: [users.id] }),
}));

// ===== Prisma 查询 vs Drizzle 查询对照 =====

// Prisma: create with nested write
// const user = await prisma.user.create({
//   data: {
//     email: 'alice@example.com',
//     name: 'Alice',
//     posts: { create: [{ title: 'Hello' }] },
//   },
//   include: { posts: true },
// });

// Drizzle: 同样的操作，用事务保证一致性
import { db } from './db';
import { users, posts } from './schema';

const userWithPost = await db.transaction(async (tx) => {
  const [user] = await tx
    .insert(users)
    .values({ email: 'alice@example.com', name: 'Alice' })
    .returning();

  const [post] = await tx
    .insert(posts)
    .values({ title: 'Hello', authorId: user.id })
    .returning();

  return { ...user, posts: [post] };
});

3.3 性能实测对比

以下是基于一个包含 10 万条用户记录、50 万条文章记录的 PostgreSQL 数据库的实测数据（Node.js 22，本地 PostgreSQL 16）：

⚡ 关键结论： Drizzle 在所有场景下都比 Prisma 快，优势最大的地方是批量操作和冷启动——这两个恰好是 Serverless 环境最敏感的指标。

3.4 Drizzle 的局限性与坑点

Drizzle 不是银弹，以下是你在选型前必须知道的限制：

❌ 避免在这些场景使用 Drizzle：

1. MongoDB 支持：Drizzle 目前只支持关系型数据库（PostgreSQL、MySQL、SQLite），不支持 MongoDB。如果你的项目强依赖 MongoDB，只能选 Prisma 或 Mongoose。

2. 团队 SQL 基础薄弱：Drizzle 的 db.select() 本质上就是写 SQL，如果团队成员不熟悉 JOIN、GROUP BY、子查询，上手成本会很高。

3. 自动 GraphQL 生成：Prisma + Pothos/Nexus 可以自动生成 GraphQL Schema，Drizzle 没有这个级别的生态支持。

4. Seeding 方案：Prisma 有官方的 prisma/seed 方案，Drizzle 需要自己写 seed 脚本或用第三方库 drizzle-seed。

⚠️ 迁移时的常见坑：

• Drizzle 的 references() 只在迁移生成时生效，不会阻止你在代码层面插入违反外键的数据
• db.query 的嵌套查询在数据量大时可能产生性能问题，需要手动优化
• Drizzle 的 drizzle-kit push 和 drizzle-kit generate 行为不一致，切换时容易混淆
• 日期类型在不同数据库驱动之间表现不一致，PostgreSQL 返回 Date 对象，SQLite 返回字符串

📊 四、最佳实践与生产建议

4.1 Schema 组织最佳实践

// ✅ 推荐：按业务域拆分 Schema 文件
// src/db/schema/
//   ├── index.ts        // 统一导出
//   ├── users.ts        // 用户相关表
//   ├── posts.ts        // 文章相关表
//   └── comments.ts     // 评论相关表

// src/db/schema/users.ts
import { pgTable, text, timestamp, uuid, boolean } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  role: text('role', { enum: ['admin', 'editor', 'viewer'] }).default('viewer').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

// src/db/schema/index.ts — 统一导出所有 Schema
export * from './users';
export * from './posts';
export * from './comments';

4.2 查询性能优化

// ❌ 避免：N+1 查询问题
const allPosts = await db.select().from(posts);
for (const post of allPosts) {
  const author = await db.select().from(users).where(eq(users.id, post.authorId));
  // 每篇文章发一次查询！如果有 100 篇文章就是 101 次查询
}

// ✅ 正确：用 JOIN 一次查询搞定
const postsWithAuthors = await db
  .select({
    postTitle: posts.title,
    postContent: posts.content,
    authorName: users.name,
    authorEmail: users.email,
  })
  .from(posts)
  .leftJoin(users, eq(posts.authorId, users.id))
  .where(eq(posts.published, true))
  .orderBy(desc(posts.createdAt))
  .limit(20);

// ✅ 批量操作：用 batch 插入代替循环插入
// ❌ 避免：循环插入
for (const item of items) {
  await db.insert(posts).values(item);
}

// ✅ 正确：批量插入
await db.insert(posts).values(items); // items 是数组，Drizzle 自动生成批量 INSERT

// ✅ 批量更新：用 upsert
await db
  .insert(posts)
  .values({ slug: 'hello', title: 'Hello World' })
  .onConflictDoUpdate({
    target: posts.slug,
    set: { title: 'Updated Title', updatedAt: new Date() },
  });

4.3 生产环境 Checklist

• ✅ 始终使用 drizzle-kit generate + drizzle-kit migrate，不用 push
• ✅ 迁移文件提交到 Git，和代码一起做 Code Review
• ✅ 为高频查询字段添加索引，用 .explain() 验证查询计划
• ✅ 使用连接池（postgres 库的 max 参数），不要每次请求新建连接
• ✅ 开启 postgres 库的 prepare: true，利用 PostgreSQL 的 prepared statements
• ⚠️ 不要在 Serverless 环境使用 postgres 的长连接模式
• ⚠️ 日期类型在跨数据库迁移时要格外注意格式一致性
• ❌ 不要依赖 db.query 做复杂聚合——它生成的 SQL 不可控
• ❌ 不要在生产环境使用 drizzle-kit push

🎯 总结

Drizzle ORM 代表了 TypeScript ORM 的新范式：不试图隐藏 SQL，而是用类型安全的方式拥抱 SQL。它的核心价值在于三个「零」：零运行时依赖、零代码生成、零抽象泄漏。对于有 SQL 基础的团队，Drizzle 在开发体验和运行性能上都显著优于 Prisma。

选型建议：

• 🟢 选 Drizzle：新项目、Edge 部署、SQL 熟练团队、性能敏感场景
• 🟡 可考虑：从 Prisma 迁移（评估迁移成本是否值得）
• 🔴 不推荐：MongoDB 项目、SQL 新手团队、需要自动生成 GraphQL 的场景

相关资源：

• 🔧 Drizzle ORM 官方文档
• 🔧 Drizzle Kit 迁移指南
• 🔧 Drizzle Studio — 在线数据浏览器
• 🔧 jsjson.com JSON 格式化工具 — 格式化你的 JSON 数据
• 🔧 jsjson.com SQL 优化指南 — 深入学习 SQL 查询优化