Drizzle Kit

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

npm i -D drizzle-kit

yarn add -D drizzle-kit

pnpm add -D drizzle-kit

bun add -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 迁移包或适合你的业务案例或个人偏好的任何其他方式。

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

import { defineConfig } from 'drizzle-kit'

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

Schema 更新

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

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 Kit 或 Drizzle 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 将自动跟踪应用于你的数据库的迁移。

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 允许你在 TypeScript、JavaScript 或 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 迅速向前推进。

当你拥有像 Neon、Planetscale 或 Turso 等远程数据库时，这非常方便。

概览

如果你想在本地开发中快速迭代或者项目不需要迁移文件，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**数据库浏览器，并让你只需一个命令就可以在本地启动。

Studio 需要提供具有 schema 和 dbCredentials 的 drizzle 配置文件。

drizzle-kit studio

drizzle-kit studio --port 3000 ## 自定义端口
drizzle-kit studio --host 0.0.0.0 ## 自定义 Studio 服务器的主机
drizzle-kit studio --verbose   ## 记录所有的 SQL 语句