Become a Gold Sponsor

drizzle-kit generate

This guide assumes familiarity with:

drizzle-kit generate 允许您根据 Drizzle 模式在声明时或后续模式更改时生成 SQL 迁移。

它是如何在后台工作的?

Drizzle Kit generate 命令触发以下事件序列:

  1. 它将读取您的 Drizzle 模式文件并创建模式的 JSON 快照
  2. 它将读取您先前的迁移文件夹并将当前 JSON 快照与最新的快照进行比较
  3. 基于 JSON 差异,它将生成 SQL 迁移
  4. 保存 migration.sqlsnapshot.json 在以当前时间戳命名的迁移文件夹中
src/schema.ts
import * as p from "./drizzle-orm/pg-core";

export const users = p.pgTable("users", {
  id: p.serial().primaryKey(),
  name: p.text(),
  email: p.text().unique(), 
};
┌────────────────────────┐                  
│ $ drizzle-kit generate │                  
└─┬──────────────────────┘                  

  └ 1. 读取先前的迁移文件夹
    2. 找到当前和先前模式之间的差异
    3. 如果需要,提示开发者重命名
  ┌ 4. 生成 SQL 迁移并持久化到文件
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 drizzle       
  │      ├ 📂 _meta
  │      └ 📜 0000_premium_mister_fear.sql
  v
-- drizzle/0000_premium_mister_fear.sql

CREATE TABLE "users" (
 "id" SERIAL PRIMARY KEY,
 "name" TEXT,
 "email" TEXT UNIQUE
);

它旨在覆盖 代码优先 的 Drizzle 迁移管理方法。 您可以使用 drizzle-kit migrate 应用生成的迁移,也可以使用 drizzle-orm 的 migrate(), 使用外部迁移工具,如 bytebase,或者直接在数据库上执行迁移。

drizzle-kit generate 命令要求您提供 dialectschema 路径选项, 您可以通过 drizzle.config.ts 配置文件或通过 CLI 选项设置它们。

使用配置文件
作为 CLI 选项
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
});
npx drizzle-kit generate

模式文件路径

您可以有一个单独的 schema.ts 文件,或者在项目中拥有任意数量的模式文件。 Drizzle Kit 要求您通过 schema 配置选项以 glob 指定路径。

Example 1
Example 2
Example 3
Example 4
📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ ...
 │ ├ 📜 index.ts
 │ └ 📜 schema.ts 
 ├ 📜 drizzle.config.ts
 └ 📜 package.json
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/schema.ts",
});

自定义迁移文件名

您可以通过提供 --name CLI 选项设置自定义迁移文件名。

npx drizzle-kit generate --name=init
📦 <项目根目录>
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ └ 📜 0000_init.sql 
 ├ 📂 src
 └ …

项目中的多个配置文件

您可以在项目中拥有多个配置文件,这在您有多个数据库阶段、多个数据库或者在同一个项目上有不同数据库时非常有用:

npm
yarn
pnpm
bun
npx drizzle-kit generate --config=drizzle-dev.config.ts
npx drizzle-kit generate --config=drizzle-prod.config.ts
📦 <项目根目录>
 ├ 📂 drizzle
 ├ 📂 src
 ├ 📜 .env
 ├ 📜 drizzle-dev.config.ts
 ├ 📜 drizzle-prod.config.ts
 ├ 📜 package.json
 └ 📜 tsconfig.json

自定义迁移

您可以生成空的迁移文件以编写自己的自定义 SQL 迁移 用于当前不被 Drizzle Kit 支持的 DDL 更改或数据填充。有关自定义迁移的扩展文档 - 点击这里

drizzle-kit generate --custom --name=seed-users
📦 <项目根目录>
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 0000_init.sql 
 │ └ 📜 0001_seed-users.sql 
 ├ 📂 src
 └ …
-- ./drizzle/0001_seed-users.sql

INSERT INTO "users" ("name") VALUES('Dan');
INSERT INTO "users" ("name") VALUES('Andrew');
INSERT INTO "users" ("name") VALUES('Dandrew');

可用配置的扩展列表

drizzle-kit generate 有一系列仅限 cli 的选项。

custom生成自定义迁移的空 SQL 文件
name生成自定义名称的迁移
npm
yarn
pnpm
bun
npx drizzle-kit push --name=init
npx drizzle-kit push --name=seed_users --custom



我们推荐通过 drizzle.config.ts 文件来配置 drizzle-kit, 但如果有必要,您也可以通过 CLI 提供所有配置选项,例如在 CI/CD 管道等中。

dialectrequired数据库方言,取值之一 postgresql mysql sqlite turso
schemarequired指向 TypeScript 模式文件或包含多个模式文件的文件夹的路径
out迁移输出文件夹,默认为 ./drizzle
config配置文件路径,默认为 drizzle.config.ts
breakpointsSQL 语句断点,默认值为 true

扩展示例

如何创建一个名为 0001_seed-users.sql 的自定义 PostgreSQL 迁移文件的示例。 Drizzle 模式位于 ./src/schema.ts,迁移文件夹名为 ./migrations,而不是默认的 ./drizzle

我们还将在 configs 文件夹中放置 drizzle 配置文件。

让我们创建配置文件:

📦 <项目根目录>
 ├ 📂 migrations
 ├ 📂 configs
 │ └ 📜 drizzle.config.ts
 ├ 📂 src
 └ …
drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  out: "./migrations",
});

现在让我们运行:

npx drizzle-kit generate --config=./configs/drizzle.config.ts --name=seed-users --custom

它将成功生成:

📦 <项目根目录>
 ├ …
 ├ 📂 migrations
 │ ├ 📂 _meta
 │ ├ 📜 0000_init.sql 
 │ └ 📜 0001_seed-users.sql 
 └ …
-- ./drizzle/0001_seed-users.sql

INSERT INTO "users" ("name") VALUES('Dan');
INSERT INTO "users" ("name") VALUES('Andrew');
INSERT INTO "users" ("name") VALUES('Dandrew');