Drizzle Kit —— Typescript生态轻量数据库版本管理方案

最近使用Hono做全栈开发,接触到Drizzle来做数据库相关的管理,体验很不错,这里简单记录分享。

Drizzle ORM 的 CLI 工具 Drizzle Kit 生成迁移时不连数据库,只靠本地 JSON 快照做对比。 同一份 schema 永远生成同样的 SQL,可以提交 Git、做 Code Review,不会因为连接不同环境或者DDL而产生差异。

本文先把核心用法过一遍,再讲解它底层的版本管理设计。

Schema 定义 —— 表结构就是 TypeScript

Drizzle 没有 .prisma 那种独立的 schema 语言,直接用 TypeScript 写表:

// src/db/schema.ts
import {
  pgTable,
  serial,
  text,
  varchar,
  integer,
  timestamp,
} from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial("id").primaryKey(), 
  email: varchar("email", { length: 255 }).notNull().unique(),
  name: text("name").notNull(),
  createdAt: timestamp("created_at").defaultNow(),
});

安装和配置也干净:

bun add drizzle-orm pg # 核心库+数据库驱动
bun add -D drizzle-kit tsx @types/pg # 开发依赖
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

dialect 指定数据库(也支持 MySQL、SQLite、Turso 等),schema 指向表定义,out 是迁移输出目录。

数据库连接:

// src/db/index.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! });
export const db = drizzle(pool, { schema });

本文以 PostgreSQL 为例,其他数据库用法一致。

push 还是 generate?

Drizzle Kit 提供两种同步 schema 到数据库的方式:

push:改完直接生效

bunx drizzle-kit push

它做的事:读 schema → 序列化为快照 → 连数据库 introspect → 算差异 → 直接执行 DDL。快速原型、单人项目、配合 Serverless 数据库(Neon、Turso)蓝绿部署,非常直接。

但它不生成 SQL 文件。 没文件就没法 Code Review,CI/CD 也不好精确控制。团队协作或生产环境看下面这套。

generate + migrate:先生成 SQL,再执行

生产级两步走。

Step 1:生成迁移文件

bunx drizzle-kit generate

第一次跑完,drizzle/ 目录长这样:

drizzle/
├── meta/
│   ├── _journal.json
│   └── 0000_snapshot.json
└── 0000_fast_iron_lad.sql

现在给 posts 加个字段:

published: boolean("published").default(false),

再跑一次:

drizzle/
├── meta/
│   ├── _journal.json
│   ├── 0000_snapshot.json
│   └── 0001_snapshot.json
├── 0000_fast_iron_lad.sql
└── 0001_eager_black_widow.sql  # 新增

文件内容如下:

ALTER TABLE "posts" ADD COLUMN "published" boolean DEFAULT false;

重命名列时有个细节: 如果你把 name 改成 fullName,Drizzle 没法自动判断这是 rename 还是 drop + add,会交互式问你:

Is fullName column in users table created or renamed from another column?

❯ ~ name › fullName  rename column
  + fullName          create column

Step 2:应用迁移

bunx drizzle-kit migrate

它连数据库 → 查 __drizzle_migrations 表 → 找出还没跑的迁移sql → 按顺序执行。同一迁移不会跑两次。

数据库迁移

到这里 SQL 文件已经有了。接下来要解决的是:生产和开发如何使用这些迁移文件来同步数据库

社区共识是:本地随意 push,线上自动 migrate,再让工具帮你确保永远不会漏掉迁移文件。

  1. 自动生成迁移sql

别靠死记”上线前记得 generate”的规范。推荐加一个 pre-commit hook,只要 staging 区里 schema.ts 有变动就自动跑一遍:

# lefthook.yml
pre-commit:
  commands:
    drizzle-generate:
      glob: "*.{ts,tsx}"
      run: |
        if git diff --cached --name-only | grep -q "schema\.ts"; then
          bunx drizzle-kit generate
          git add drizzle/
        fi

Husky 同理,把核心逻辑搬到 .husky/pre-commit 里即可。

这样每次 commit 的 .sql 一定和最新 schema 同步。

  1. 启动前自动执行迁移

本地开发数据丢了无所谓,bunx drizzle-kit push 直接生效,不产生文件、不打断思路。

但生产环境必须走 migrate() —— 应用启动前自动执行,推荐按 NODE_ENV 判断要不要跑:

// src/server.ts
import { migrate } from "drizzle-orm/node-postgres/migrator";

if (process.env.NODE_ENV === "production") {
  await migrate(db, { migrationsFolder: "./drizzle" });
}
// 迁移跑完才启动 server

如果你需要在迁移里改数据

Drizzle Kit 生成的 SQL 是纯 DDL(建表、改列、加索引),不管数据。真要迁移数据(比如把 name 拆成 first_name + last_name),直接在生成的 .sql 文件后面补 DML 就行:

ALTER TABLE "users" ADD COLUMN "first_name" text;
ALTER TABLE "users" ADD COLUMN "last_name" text;

-- 手动补充:数据迁移
UPDATE "users" SET
  "first_name" = split_part("name", ' ', 1),
  "last_name" = split_part("name", ' ', 2);

seed 和 studio —— 开发体验提升必备

seed:填充测试数据

drizzle-seed 是官方提供的种子数据工具,装包即用:

bun add drizzle-seed

相比手写 SQL 脚本或第三方造数库,drizzle-seed 最大优势是与你的 Drizzle schema 共享类型定义:schema 一改,seed 编译报错,不会出现”改了表结构忘了更新造数脚本”的低级错误。

studio:小而美的数据库 Web UI

bunx drizzle-kit studio

跑起来后在 https://local.drizzle.studio 打开一个网页:浏览表、查数据、编辑记录、看外键关联。日常调试够用, 不需要额外DBMS。

完整工作流

Local Development schema.ts → drizzle-kit push (instant feedback) rapid iteration Pre-commit schema.ts → drizzle-kit generate → review SQL files generate migration Deployment startup script → migrate() → auto-apply migrations production rollout Debugging drizzle-kit studio → visual browse / edit data dev loop Reset bun run seed.ts → truncate and refill test data

原理简述:它为什么可靠?

generate 不连数据库,凭什么知道要生成什么 SQL? 我们现在深入看看之前提到的:meta/ 目录、snapshot 快照、__drizzle_migrations 表。

meta/ 目录

每次 generate,Drizzle会在本地存一份完整 schema 历史:

drizzle/
├── meta/
│   ├── _journal.json          # 迁移目录清单
│   ├── 0000_snapshot.json     # 初始 schema 快照
│   └── 0001_snapshot.json     # 第一次变更后的 schema 快照
├── 0000_fast_iron_lad.sql
└── 0001_eager_black_widow.sql

_journal.json 就是目录:

{
  "version": "7",
  "dialect": "postgresql",
  "entries": [
    {
      "idx": 0,
      "version": "7",
      "when": 1709553600000,
      "tag": "0000_fast_iron_lad",
      "breakpoints": true
    },
    {
      "idx": 1,
      "version": "7",
      "when": 1709640000000,
      "tag": "0001_eager_black_widow",
      "breakpoints": true
    }
  ]
}

entries 按时间列出所有迁移,tag 对应文件名前缀。XXXX_snapshot.json 才是核心 —— 它是当前 schema 的完整序列化:

// XXXX_snapshot.json
{
  "version": "7",
  "dialect": "postgresql",
  "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "prevId": "00000000-0000-0000-0000-000000000000",
  "tables": {
    "users": {
      "name": "users",
      "columns": {
        "id": {
          "name": "id",
          "type": "serial",
          "primaryKey": true,
          "notNull": true
        },
        "email": {
          "name": "email",
          "type": "varchar",
          "primaryKey": false,
          "notNull": true
        },
        "name": {
          "name": "name",
          "type": "text",
          "primaryKey": false,
          "notNull": true
        }
      },
      "indexes": {},
      "foreignKeys": {}
    }
  },
  "enums": {},
  "schemas": {}
}

注意两个关键字段:

  • id:当前快照的唯一标识
  • prevId:指向上一个快照的 id

id → prevId 构成一条单向链表。 每个快照都知道”我是从哪个状态变过来的”。

generate行为示意图

drizzle-kit generate 1. Read schema.ts Generate current JSON snapshot 2. Read latest snapshot Read latest snapshot from meta/ 3. diff(current, latest) → compute DDL changes + Table added → CREATE TABLE − Table dropped → DROP TABLE + Column added → ALTER TABLE ADD COLUMN − Column dropped → ALTER TABLE DROP COLUMN ~ Type changed → ALTER TABLE ALTER COLUMN TYPE ? Rename detected → interactive confirmation 4. Generate XXXX_tag.sql 5. Save latest snapshot meta/000N_snapshot.json 6. Update _journal.json entries

总结一下看就四步:

  1. 读取当前 TypeScript schema,序列化为新的 snapshot JSON
  2. 从 _journal.json 找到最后一条记录,加载对应的上一个 snapshot
  3. 对比两个 snapshot,算出差异(加了哪些列、删了哪些表、改了哪些索引…)
  4. 把差异翻译成目标数据库的 DDL SQL,写入 .sql 文件

全程是不碰数据库的。

这意味着:离线也能生成迁移(CI/CD 不需要数据库);同一份 schema 永远生成同样的 SQL;prevId 链表保证快照链完整 —— 中间少一个 snapshot,下次 generate 直接报错。

__drizzle_migrations —— 生产数据库里的执行日志

generate 确保了”生成稳定正确的迁移SQL”,migrate 则负责跟踪”哪些 SQL 还没跑”,这样无论哪个版本的数据库都可以丝滑迁移到最新。后者靠数据库里的一张表:

-- PostgreSQL 下默认在 drizzle schema,源码中的建表语句
TABLE drizzle.__drizzle_migrations (
  id          serial PRIMARY KEY,
  hash        text NOT NULL,
  created_at  bigint
);
字段干嘛的
hash迁移文件的 SHA256,保证文件没被篡改
created_at对应 _journal.json 中该迁移的 when(毫秒时间戳)

有趣的是:表里并没有 name 字段。迁移文件名(0000_fast_iron_lad)只存在于 _journal.json 的 tag 字段中。Drizzle 通过 created_at 时间戳而非文件名来判断哪些迁移已执行。

所以在 GitHub Discussion 里有老哥吐槽为什么 Drizzle 不直接存迁移文件名而是存的hash导致debug不便!

migrate 的执行逻辑是:读 _journal.json → 查 __drizzle_migrations 拿到最大的 created_at → 遍历所有 migration,folderMillis > 已记录的最大 created_at 的就是待执行列表 → 按 _journal.json 中 entries 顺序逐个跑 → 每跑完一个插一条 (hash, created_at) 记录。

补充一个关于迁移事务的参考信息:PostgreSQL 下,所有待执行的迁移文件被包在同一个事务里,这在操作 enum 等场景下会带来麻烦,GitHub Issue #3249 专门讨论了这个问题。而MySQL / SQLite / SingleStore 不支持 DDL 事务,因此依赖 --> statement-breakpoint 分隔符逐条执行,每条 DDL 隐式自动提交。

完整架构一览

Local / Git Repository src/db/schema.ts users · posts · comments drizzle-kit generate drizzle/ meta/ _journal.json 0000_snapshot.json 0001_snapshot.json 0000_fast_iron_lad.sql 0001_eager_black_widow.sql id → prevId chain guarantees snapshot integrity migrate Database Server __drizzle_migrations id hash created_at 1 d4e5f6a7b8.. 1709553600000 2 b3c4d5e6f7.. 1709640000000 Business Tables users posts comments _journal.when ↔ __drizzle_migrations.created_at compare timestamps → find pending → execute DDL

总结

本地 snapshot.json 快照追踪每次 schema 变更 → generate 对比新旧快照生成 SQL → migrate 查 __drizzle_migrations 表执行未跑的文件。 全程离线稳定、可审查记录。