Drizzle ORM 完全指南：TypeScript 优先的数据库开发新范式

2026 年，Drizzle ORM 的 npm 周下载量已突破 350 万，成为 TypeScript 生态中增长最快的 ORM。它不是又一个「把 SQL 包一层」的抽象层，而是一个以类型推导为核心、SQL 为底层的数据库工具包。与 Prisma 的「Schema-first」理念不同，Drizzle 让你用纯 TypeScript 代码定义 Schema，然后在编译期自动生成完整的类型系统——查询时的字段提示、关联加载、返回值类型全部由编译器保证，零运行时开销。如果你厌倦了 Prisma 的 prisma generate 黑箱和慢启动，或者觉得 TypeORM 的装饰器模式过于 Java 化，这篇文章会给你一个彻底不同的选择。

🔧 一、Schema 设计：用代码定义一切

1.1 为什么 Schema-first（代码优先）更好

Prisma 使用独立的 .prisma 文件定义 Schema，然后通过 codegen 生成 TypeScript 类型。这个设计有两个根本问题：

• ✅ Drizzle 的方式：Schema 就是 TypeScript 代码，改了 Schema 类型自动更新，不需要任何构建步骤
• ❌ Prisma 的方式：改了 .prisma 文件后必须运行 prisma generate，否则 TypeScript 编译器不知道类型变了

Drizzle 的 Schema 定义是纯函数调用，不依赖装饰器、注解或任何魔法。下面是一个完整的 PostgreSQL Schema 示例：

// schema.ts — Drizzle Schema 定义（PostgreSQL）
import { pgTable, uuid, varchar, text, integer, timestamp, boolean, jsonb, index, uniqueIndex } from 'drizzle-orm/pg-core'

// 用户表
export const users = pgTable('users', {
  id: uuid('id').defaultRandom().primaryKey(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  name: varchar('name', { length: 100 }).notNull(),
  avatar: text('avatar'),
  role: varchar('role', { length: 20 }).default('user').notNull(),
  metadata: jsonb('metadata').$type<Record<string, unknown>>(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
}, (table) => [
  // 索引定义与表结构放在一起，清晰明了
  index('idx_users_email').on(table.email),
  index('idx_users_role').on(table.role),
  uniqueIndex('idx_users_email_unique').on(table.email),
])

// 文章表
export const posts = pgTable('posts', {
  id: uuid('id').defaultRandom().primaryKey(),
  title: varchar('title', { length: 200 }).notNull(),
  content: text('content').notNull(),
  slug: varchar('slug', { length: 200 }).notNull(),
  status: varchar('status', { length: 20 }).default('draft').notNull(),
  viewCount: integer('view_count').default(0).notNull(),
  authorId: uuid('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  publishedAt: timestamp('published_at'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
}, (table) => [
  index('idx_posts_author').on(table.authorId),
  index('idx_posts_slug').on(table.slug),
  index('idx_posts_status').on(table.status),
])

// 标签表
export const tags = pgTable('tags', {
  id: uuid('id').defaultRandom().primaryKey(),
  name: varchar('name', { length: 50 }).notNull().unique(),
  slug: varchar('slug', { length: 50 }).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) => [
  // 联合主键：确保同一文章不会重复关联同一标签
  uniqueIndex('idx_post_tags_unique').on(table.postId, table.tagId),
])

💡 提示： Drizzle 的 $type<T>() 方法让你在 Schema 定义中声明 JSON 字段的具体 TypeScript 类型。这意味着 jsonb 字段在查询结果中不是 any，而是你定义的精确类型。这是 Prisma 做不到的——Prisma 的 Json 类型在运行时是 Prisma.JsonValue，需要手动断言。

1.2 关系定义：声明式 vs 函数式

Drizzle 提供两种定义关系的方式，各有适用场景：

// relations.ts — Drizzle 关系定义
import { relations } from 'drizzle-orm'
import { users, posts, tags, postTags } from './schema'

// 方式一：声明式关系（推荐，适合简单场景）
export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}))

export const postsRelations = relations(posts, ({ one, many }) => ({
  // 一对一：每个文章属于一个作者
  author: one(users, {
    fields: [posts.authorId],
    relationsFrom: [users.id],
    relationName: 'author',
  }),
  // 多对多：通过中间表
  tags: many(postTags),
}))

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

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

⚠️ 警告： Drizzle 的 relations() 函数是可选的。它只影响 query API 的关联加载能力，不影响表结构和迁移。如果你只用 Drizzle 的 select/insert/update/delete（SQL builder 模式），完全不需要定义关系。但如果你想用 db.query.posts.findMany({ with: { author: true } }) 这种简洁语法，关系定义是必须的。

🚀 二、查询引擎：SQL Builder 与关系查询的双模式

2.1 SQL Builder 模式：精确控制

Drizzle 的 SQL Builder 模式让你用 TypeScript 写出几乎等价于原生 SQL 的查询，但所有类型都由编译器推导：

// sql-builder.ts — Drizzle SQL Builder 模式
import { eq, and, gte, lte, sql, desc, count, ilike, inArray } from 'drizzle-orm'
import { db } from './db'
import { users, posts, tags, postTags } from './schema'

// 查询示例 1：条件过滤 + 分页
async function searchPosts(params: {
  keyword?: string
  status?: string
  page: number
  pageSize: number
}) {
  const { keyword, status, page, pageSize } = params

  // 构建动态 WHERE 条件
  const conditions = []
  if (keyword) {
    conditions.push(ilike(posts.title, `%${keyword}%`))
  }
  if (status) {
    conditions.push(eq(posts.status, status))
  }

  // 查询总数
  const [{ total }] = await db
    .select({ total: count() })
    .from(posts)
    .where(and(...conditions))

  // 查询分页数据
  const data = await db
    .select({
      id: posts.id,
      title: posts.title,
      slug: posts.slug,
      status: posts.status,
      viewCount: posts.viewCount,
      publishedAt: posts.publishedAt,
      authorName: users.name,
      authorEmail: users.email,
    })
    .from(posts)
    .leftJoin(users, eq(posts.authorId, users.id))
    .where(and(...conditions))
    .orderBy(desc(posts.createdAt))
    .limit(pageSize)
    .offset((page - 1) * pageSize)

  return { data, total, page, pageSize }
}

// 查询示例 2：聚合查询
async function getAuthorStats() {
  return db
    .select({
      authorId: posts.authorId,
      authorName: users.name,
      postCount: count(posts.id),
      totalViews: sql<number>`sum(${posts.viewCount})`,
      avgViews: sql<number>`round(avg(${posts.viewCount}), 0)`,
    })
    .from(posts)
    .innerJoin(users, eq(posts.authorId, users.id))
    .groupBy(posts.authorId, users.name)
    .orderBy(desc(count(posts.id)))
}

// 查询示例 3：批量操作 + 事务
async function publishPost(postId: string, tagIds: string[]) {
  return db.transaction(async (tx) => {
    // 更新文章状态
    const [updated] = await tx
      .update(posts)
      .set({ status: 'published', publishedAt: new Date(), updatedAt: new Date() })
      .where(eq(posts.id, postId))
      .returning()

    if (!updated) {
      throw new Error('文章不存在')
    }

    // 清除旧标签关联
    await tx.delete(postTags).where(eq(postTags.postId, postId))

    // 批量插入新标签关联
    if (tagIds.length > 0) {
      await tx.insert(postTags).values(
        tagIds.map(tagId => ({ postId, tagId }))
      )
    }

    return updated
  })
}

2.2 关系查询模式：简洁高效

当你需要加载关联数据时，Drizzle 的 query API 比 SQL Builder 简洁得多：

// relational-query.ts — Drizzle 关系查询
import { db } from './db'

// 查询文章列表，自动加载作者和标签
const postsWithRelations = await db.query.posts.findMany({
  with: {
    author: {
      columns: {
        id: true,
        name: true,
        avatar: true,
        // 排除敏感字段
        email: false,
      },
    },
    tags: {
      with: {
        tag: true,
      },
    },
  },
  where: (posts, { eq }) => eq(posts.status, 'published'),
  orderBy: (posts, { desc }) => [desc(posts.publishedAt)],
  limit: 20,
})

// 查询单篇文章（带完整关联）
const post = await db.query.posts.findFirst({
  with: {
    author: true,
    tags: {
      with: {
        tag: true,
      },
    },
  },
  where: (posts, { eq }) => eq(posts.slug, 'my-first-post'),
})

⚡ 关键结论： Drizzle 的关系查询不会产生 N+1 问题。它在内部使用 SQL JOIN 而不是多次查询，性能与手写 SQL 基本一致。这一点比 Prisma 的 include 更透明——Prisma 在某些场景下会生成多条 SQL 查询。

2.3 与 Prisma 和原生 SQL 的性能对比

以下基准测试在相同硬件（4 核 8GB，PostgreSQL 16）上执行，查询 10 万条用户数据：

⚡ 关键结论： Drizzle 的查询性能仅比原生 SQL 慢 7-11%，而 Prisma 慢 129-173%。关键差异在于：Drizzle 在编译期就把 Schema 转换为 SQL 元数据，运行时只做参数绑定；Prisma 需要在运行时解析查询引擎（Rust binary），引入了显著的序列化开销和冷启动延迟。

💡 三、迁移系统与生产实践

3.1 Drizzle Kit：自动生成迁移

Drizzle 的迁移工具 drizzle-kit 能自动对比 Schema 变更，生成可审查的 SQL 迁移文件：

# 生成迁移文件（对比当前 Schema 与数据库实际状态）
npx drizzle-kit generate

# 执行迁移
npx drizzle-kit migrate

# 推送 Schema 到数据库（开发环境快速迭代，不生成迁移文件）
npx drizzle-kit push

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

// drizzle.config.ts — Drizzle Kit 配置文件
import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  schema: './src/db/schema.ts',       // Schema 文件路径
  out: './drizzle/migrations',         // 迁移文件输出目录
  dialect: 'postgresql',               // 数据库方言
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  // 生产环境安全设置
  strict: true,                        // 禁止破坏性变更
  verbose: true,                       // 输出详细日志
})

📌 记住： drizzle-kit push 和 drizzle-kit migrate 是两个完全不同的命令。push 直接修改数据库结构，适合开发环境快速原型；generate + migrate 生成可版本控制的 SQL 文件，适合生产环境。永远不要在生产环境使用 push。

3.2 生产环境避坑指南

在生产环境中使用 Drizzle ORM，以下是最常见的坑点和应对策略：

// connection-pool.ts — 生产级数据库连接配置
import { drizzle } from 'drizzle-orm/node-postgres'
import { Pool } from 'pg'
import * as schema from './schema'

// 连接池配置
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  // 生产环境关键参数
  max: 20,                    // 最大连接数（根据数据库规格调整）
  idleTimeoutMillis: 30000,   // 空闲连接超时 30s
  connectionTimeoutMillis: 5000, // 连接超时 5s
  // SSL 配置（云数据库通常需要）
  ssl: process.env.NODE_ENV === 'production'
    ? { rejectUnauthorized: false }
    : false,
})

// 创建 Drizzle 实例
export const db = drizzle(pool, { schema })

// 优雅关闭
process.on('SIGTERM', async () => {
  await pool.end()
  process.exit(0)
})

常见坑点清单：

⚠️ 警告： Drizzle 的 $type<T>() 只影响 TypeScript 类型推导，不参与运行时验证。如果你的数据库中存了一个不合法的 JSON，Drizzle 会直接返回原始数据并按你声明的类型处理，不会报错。生产环境建议在读取后用 Zod 做一次运行时校验。

3.3 与 tRPC 的深度集成

Drizzle 的类型推导与 tRPC 的类型安全天然契合。以下是一个完整的 API 路由示例：

// router.ts — tRPC + Drizzle 完整集成
import { initTRPC, TRPCError } from '@trpc/server'
import { z } from 'zod'
import { eq } from 'drizzle-orm'
import { db } from './db'
import { posts, users } from './schema'

const t = initTRPC.create()
const router = t.router
const publicProcedure = t.procedure

export const appRouter = router({
  // 获取文章列表（Drizzle 推导出的类型直接传递给 tRPC）
  getPosts: publicProcedure
    .input(z.object({
      page: z.number().min(1).default(1),
      pageSize: z.number().min(1).max(50).default(10),
    }))
    .query(async ({ input }) => {
      const data = await db
        .select({
          id: posts.id,
          title: posts.title,
          slug: posts.slug,
          status: posts.status,
          authorName: users.name,
        })
        .from(posts)
        .leftJoin(users, eq(posts.authorId, users.id))
        .limit(input.pageSize)
        .offset((input.page - 1) * input.pageSize)

      // tRPC 自动推导出返回值类型
      return data
    }),

  // 创建文章（返回值类型由 Drizzle 的 .returning() 自动推导）
  createPost: publicProcedure
    .input(z.object({
      title: z.string().min(1).max(200),
      content: z.string().min(1),
      slug: z.string().min(1),
      authorId: z.string().uuid(),
    }))
    .mutation(async ({ input }) => {
      const [newPost] = await db
        .insert(posts)
        .values(input)
        .returning()

      if (!newPost) {
        throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: '创建失败' })
      }

      return newPost
    }),
})

export type AppRouter = typeof appRouter

💡 提示： Drizzle + tRPC 的组合实现了真正的「端到端类型安全」。从数据库 Schema → Drizzle 查询类型 → tRPC 返回类型 → 前端调用，整条链路的类型都由 TypeScript 编译器自动推导。改一个数据库字段，前端编译立刻报错——这就是 TypeScript 全栈开发的终极形态。

📊 四、方案选型决策树

在选择 ORM 时，没有「最好」只有「最合适」。以下是基于实际项目经验的决策建议：

✅ 总结与建议

Drizzle ORM 代表了 TypeScript 数据库工具的一个新方向：不是把 SQL 藏起来，而是让 SQL 更安全。它不做 ORM 领域常见的「抽象泄漏」——不试图把关系型数据库伪装成对象图，而是让你用 TypeScript 写出等价的 SQL，同时获得完整的类型检查和自动补全。

核心优势回顾：

• ⚡ 性能接近原生 SQL — 仅 7-11% 的额外开销，Prisma 则是 129-173%
• 🔒 编译期类型安全 — Schema 改了类型自动更新，零 codegen 步骤
• 🚀 零冷启动 — 不像 Prisma 需要加载 Rust query engine binary
• 📦 包体积小 — 核心包约 20KB gzip，Prisma Client 约 2MB+

推荐的学习路径：

1. 从 Drizzle 官方文档 的 Quick Start 开始
2. 用 drizzle-kit studio 可视化理解 Schema 和数据
3. 先用 SQL Builder 模式熟悉 API，再尝试关系查询
4. 生产环境务必配置连接池和迁移流程

相关工具推荐：

• 🔧 Drizzle Kit — Schema 迁移与管理工具
• 🔧 Drizzle Studio — 可视化数据库浏览器
• 🔧 Neon — Serverless PostgreSQL，与 Drizzle 天然适配
• 🔧 Supabase — 开源 BaaS，官方 Drizzle 集成指南
• 🔧 tRPC — 端到端类型安全 API 框架
• 📝 Drizzle vs Prisma 对比文章 — 我们之前写过的详细对比