`drizzle-kit generate`

This guide assumes familiarity with:

开始使用 Drizzle 和 drizzle-kit - 点击此处阅读
Drizzle 模式基础知识 - 点击此处阅读
数据库连接基础知识 - 点击此处阅读
Drizzle 迁移基础知识 - 点击此处阅读
Drizzle Kit overview 和配置文件

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

How it works under the hood?

Drizzle Kit generate 命令会触发一系列事件：

它将读取你的 Drizzle 模式文件并编写你的模式的 JSON 快照
它将读取你之前的迁移文件夹，并将当前 JSON 快照与最新的快照进行比较
根据 JSON 差异，生成 SQL 迁移
将 migration.sql 和 snapshot.json 保存在当前时间戳下的迁移文件夹中。

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. read previous migration folders
    2. find diff between current and previous scheama
    3. prompt developer for renames if necessary
  ┌ 4. generate SQL migration and persist to file
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 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 命令要求你提供 dialect 和 schema 路径选项，你可以通过 drizzle.config.ts 配置文件或 CLI 选项进行设置。

With config file

As CLI options

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

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

npx drizzle-kit generate

npx drizzle-kit generate --dialect=postgresql --schema=./src/schema.ts

Schema 文件路径

你可以拥有一个 schema.ts 文件，也可以在整个项目中分布任意数量的模式文件。Drizzle Kit 要求你将这些模式文件的路径指定为 glob via schema 配置选项。

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",
});

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ 📂 user
 │ │ ├ 📜 handler.ts 
 │ │ └ 📜 schema.ts 
 │ ├ 📂 posts
 │ │ ├ 📜 handler.ts 
 │ │ └ 📜 schema.ts 
 │ └ 📜 index.ts
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/**/schema.ts",
  //or
  schema: ["./src/user/schema.ts", "./src/posts/schema.ts"]
});

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ 📂 schema
 │ │ ├ 📜 user.ts 
 │ │ ├ 📜 post.ts 
 │ │ └ 📜 comment.ts 
 │ └ 📜 index.ts
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import { defineConfig } from "drizzle-kit";

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

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 │ ├ 📜 userById.ts 
 │ ├ 📜 userByEmail.ts 
 │ ├ 📜 listUsers.ts 
 │ ├ 📜 user.sql.ts 
 │ ├ 📜 postById.ts 
 │ ├ 📜 listPosts.ts 
 │ └ 📜 post.sql.ts 
 │ 📜 index.ts
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/**/*.sql.ts", // Dax's favourite
});

自定义迁移文件名

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

npx drizzle-kit generate --name=init

📦 <project root>
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ └ 📜 0000_init.sql 
 ├ 📂 src
 └ …

一个项目中的多个配置文件

项目中可以有多个配置文件，当同一个项目有多个数据库阶段或多个数据库或不同的数据库时，这非常有用：

npm

yarn

pnpm

bun

npx drizzle-kit 生成 --config=drizzle-dev.config.ts drizzle-kit 生成 --config=drizzle-prod.config.ts

yarn drizzle-kit 生成 --config=drizzle-dev.config.ts drizzle-kit 生成 --config=drizzle-prod.config.ts

pnpm drizzle-kit 生成 --config=drizzle-dev.config.ts drizzle-kit 生成 --config=drizzle-prod.config.ts

bun drizzle-kit 生成 --config=drizzle-dev.config.ts drizzle-kit 生成 --config=drizzle-prod.config.ts

📦 <project root>
 ├ 📂 drizzle
 ├ 📂 src
 ├ 📜 .env
 ├ 📜 drizzle-dev.config.ts
 ├ 📜 drizzle-prod.config.ts
 ├ 📜 package.json
 └ 📜 tsconfig.json

自定义迁移

你可以生成空的迁移文件，以便为 Drizzle Kit 当前不支持的 DDL 替换或数据播种编写自定义 SQL 迁移。自定义迁移的扩展文档 - 参见此处

drizzle-kit generate --custom --name=seed-users

📦 <project root>
 ├ 📂 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 包含一系列仅限命令行选项


`custom`	为自定义迁移生成空 SQL
`name`	生成自定义名称的迁移

npm

yarn

pnpm

bun

npx drizzle-kit 生成 --name=init drizzle-kit 生成 --name=seed_users --custom

yarn drizzle-kit 生成 --name=init drizzle-kit 生成 --name=seed_users --custom

pnpm drizzle-kit 生成 --name=init drizzle-kit 生成 --name=seed_users --custom

bun drizzle-kit 生成 --name=init drizzle-kit 生成 --name=seed_users --custom

我们建议通过 drizzle.config.ts 文件配置 drizzle-kit，但你也可以根据需要通过 CLI 提供所有配置选项，例如在 CI/CD 管道中等。


`dialect`	`required`	数据库方言，`postgresql` `mysql` `sqlite` `turso` `singlestore` 之一
`schema`	`required`	TypeScript 模式文件或包含多个模式文件的文件夹的路径
`out`		迁移输出文件夹，默认为 `./drizzle`
`config`		配置文件路径，默认为 `drizzle.config.ts`
`breakpoints`		SQL 语句断点，默认值为 `true`

扩展示例

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

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

让我们创建配置文件：

📦 <project root>
 ├ 📂 migrations
 ├ 📂 configs
 │ └ 📜 drizzle.config.ts
 ├ 📂 src
 └ …

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

它将成功生成

📦 <project root>
 ├ …
 ├ 📂 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');