Drizzle Kit

我们 Drizzle ORM 最基本的设计原则是始终明确、提供选择性解决方案并且不进行干预。我们的迁移工具包也不例外。

npm
yarn
pnpm
bun
npm i -D drizzle-kit

概览

Drizzle Kit 是用于生成自动 SQL 迁移和快速原型开发的 CLI 工具。

从概念上讲,它非常简单,你只需要声明一个 Drizzle ORM 的 TypeScript schema,然后从中生成一个 SQL 迁移。

然后你可以更改原始的 schema,Drizzle Kit 将生成新的迁移,这样你就可以在一个类型安全的地方拥有 DDL 的真实源,并进行版本控制。

Drizzle Kit 允许你将 schema 拆分到不同的文件中,甚至在一个项目中为不同的数据库有多个 schemas。你可以快速原型数据库 schema 并直接推送到数据库。

值得一提的是,你可以在几秒钟内从现有的数据库中拉取 schema ⚡️

迁移文件

迁移历史存储在 migrations 文件夹中的 .sql 文件中

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 0000_premium_mister_fear.sql
 │ ├ 📜 0001_absurd_toad.sql
 │ ├ 📜 0002_adorable_human_torch.sql
 │ └ 📜 0003_boring_silver_sable.sql
 ├ ...
 ├ 📂 src
 ├ 📜 package.json
 └ ...

每个 SQL 迁移文件包含你在数据库中应用的语句。 你可以使用 Drizzle ORM 迁移包或适合你的业务案例或个人偏好的任何其他方式。

0000_premium_mister_fear.sql
schema.ts
CREATE TABLE IF NOT EXISTS "user" (
  "id" serial,
  "name" text,
  "email" text,
  "password" text,
  "role" text,
  "created_at" timestamp,
  "updated_at" timestamp
);
export const user = pgTable("user", {
  id: serial("id"),
  name: text("name"),
  email: text("email"),
  password: text("password"),
  role: text("role").$type<"admin" | "customer">(),
  createdAt: timestamp("created_at"),
  updatedAt: timestamp("updated_at"),
});

You can also configure the prefixes for migrations, so they can be in a format that is compliant with the migration tool you are using or for your own convenience, for example Supabase would need 20240710095007_*.sql format and drizzle has 0000_*.sql be default

You can check all the prefix options here

💡

You can use prefixes only if you don’t have any migration history already. The kit won’t work properly if you mix prefix formats within the same migration folder. Please ensure you use only one prefix format throughout the project.

We are working on making it possible to migrate from one prefix format to another and to ensure interoperability

drizzle.config.ts
import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  schema: "./schema.ts",
  dialect: 'postgresql',
  migrations: {
    prefix: 'supabase'
  }
})

Schema 更新

每当你对 schema 进行更改时,只需要重新运行 $ drizzle-kit generate, 它将根据大多数情况自动为你生成 SQL 迁移。

0001_absurd_toad.sql
schema.ts
ALTER TABLE "user" ADD COLUMN "is_verified" boolean;
export const user = pgTable("user", {
  id: serial("id"),
  name: text("name"),
  email: text("email"),
  password: text("password"),
  isVerified: boolean("is_verified"),
  role: text("role").$type<"admin" | "customer">(),
  createdAt: timestamp("created_at"),
  updatedAt: timestamp("updated_at"),
});

运行迁移

我们对如何运行迁移不持有意见,您可以手动运行它们使用 SQL 生成的文件,使用外部工具等等,或者使用 Drizzle KitDrizzle ORM

使用 Drizzle Kit

您可以使用本地迁移 CLI 命令 drizzle-kit migrate。 它将从 drizzle.config.ts 文件中获取所有需要的信息来运行迁移,前提是之前已经运行了 drizzle-kit generate

您可以在 drizzle.config.ts 中指定自定义模式和迁移表名称。有关更多信息,请查看文档

# 您需要在调用此命令之前运行 `drizzle-kit generate`。
drizzle-kit migrate

使用 Drizzle ORM

我们还为你提供了一种有用的方式来运行生成的迁移,即使用特殊地为每个驱动程序和方言实现的 migrate 函数。

Drizzle 将自动跟踪应用于你的数据库的迁移。

ℹ️

drizzlemigrate 的导入取决于你正在使用的数据库驱动

PostgreSQL
MySQL
SQLite
import { drizzle } from "drizzle-orm/postgres-js";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import postgres from "postgres";

const sql = postgres("...", { max: 1 })
const db = drizzle(sql);

await migrate(db, { migrationsFolder: "drizzle" });

await sql.end();
import { drizzle } from "drizzle-orm/mysql2";
import { migrate } from "drizzle-orm/mysql2/migrator";
import { createConnection } from "mysql2";

const connection = createConnection("...")
const db = drizzle(connection);

await migrate(db, { migrationsFolder: "drizzle" });

await connection.end();
import { drizzle } from "drizzle-orm/better-sqlite3";
import { migrate } from "drizzle-orm/better-sqlite3/migrator";
import Database from "better-sqlite3";

const betterSqlite = new Database(":memory:");
const db = drizzle(betterSqlite);

migrate(db, { migrationsFolder: "drizzle" });

betterSqlite.close()

配置

Drizzle Kit 允许你在 TypeScriptJavaScriptJSON 配置文件中声明配置。

你可以享受自动补全的体验和非常便利的环境变量流程!

drizzle.config.ts
drizzle.config.js
drizzle.config.json
import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  schema: "./schema.ts",
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DB_URL,
  },
  verbose: true,
  strict: true,
})
/** @type { import("drizzle-kit").Config } */
export default {
  schema: "./schema.ts",
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DB_URL,
  }
};
{
  "dialect": "postgresql",
  "out": "./migrations-folder",
  "schema": "./src/db",
  "breakpoints": false
}

有关所有配置参数的列表,请参阅**这里**。

使用 db push 进行原型开发

Drizzle Kit 允许你更改数据库 schema 并使用 db push command 迅速向前推进。

当你拥有像 NeonPlanetscaleTurso 等远程数据库时,这非常方便。

概览

如果你想在本地开发中快速迭代或者项目不需要迁移文件,Drizzle 提供了一个好用的命令 drizzle-kit push

什么时候需要使用 ‘push’ 命令?

  1. 在本地环境中 schema 的原型和实验阶段。
  2. 当你使用管理迁移和 schema 变更的外部提供商时(例如 PlanetScale)。
  3. 在你的代码更改可以部署之前,你可以修改数据库 schema。

工作原理

当你运行 drizzle-kit push 命令时,Drizzle 执行以下步骤:

  1. 它从数据库中检索你的 schema,并将其转换为 “drizzle-schema” 格式。
  2. 该命令还会读取包含 drizzle 表的所有 schema 文件,并将其转换为 “drizzle-schema” 格式。
  3. 接下来,Drizzle 将比较这两个 schemas,并生成一组需要在你的数据库上执行的语句。 这些语句确保数据库与你代码中定义的 schema 同步。
$ drizzle-kit push

有关扩展的 push 示例,请参阅这里

使用 db pull 进行自省

Drizzle Kit 允许你从现有数据库中拉取 DDL,并完全自动打印一个 TypeScript schema 文件。

$ drizzle-kit introspect
📦 <project root>
 ├ ...
 ├ 📂 drizzle
 │ ├ 📂 _meta
 │ ├ 📜 0000_premium_mister_fear.sql
 │ └ 📜 schema.ts
 ├ ...
 ├ 📂 src
 ├ 📜 package.json
 └ ...
 export const user = pgTable("user", {
    id: serial("id"),
    name: text("name"),
    email: text("email"),
    password: text("password"),
    role: text("role").$type<"admin" | "customer">(),
    createdAt: timestamp("created_at"),
    updatedAt: timestamp("updated_at"),
  });

有关扩展的 introspect 示例,请**参阅此处**。

Drizzle Studio

Drizzle Kit 带有捆绑的**Drizzle Studio**数据库浏览器,并让你只需一个命令就可以在本地启动。

Drizzle Studio

Studio 需要提供具有 schemadbCredentials 的 drizzle 配置文件。

drizzle-kit studio

drizzle-kit studio --port 3000 ## 自定义端口
drizzle-kit studio --host 0.0.0.0 ## 自定义 Studio 服务器的主机
drizzle-kit studio --verbose   ## 记录所有的 SQL 语句
🖥 Drizzle Studio 演示 🖥 打开 Drizzle Studio
Become a Gold Sponsor