Become a Gold Sponsor

drizzle-kit push

This guide assumes familiarity with:

drizzle-kit push 允许你直接将你的模式及后续的模式变化推送到数据库, 同时省略 SQL 文件的生成, 旨在覆盖 Drizzle 迁移的 代码优先 方法。

它是如何在内部工作的?

当你运行 Drizzle Kit 的 push 命令时,它会:

  1. 读取你的 Drizzle 模式文件并组成一个 JSON 快照
  2. 拉取(内省)数据库模式
  3. 根据这两者之间的差异生成 SQL 迁移
  4. 将 SQL 迁移应用到数据库
src/schema.ts
import * as p from "drizzle-orm/pg-core";

export const users = p.pgTable("users", {
  id: p.serial().primaryKey(),
  name: p.text(),
};
┌─────────────────────┐                  
│ ~ drizzle-kit push  │                  
└─┬───────────────────┘                  
  │                                           ┌──────────────────────────┐
  └ Pull current datatabase schema ---------> │                          │
                                              │                          │
  ┌ Generate alternations based on diff <---- │         DATABASE         │
  │                                           │                          │
  └ Apply migrations to the database -------> │                          │
                                       │      └──────────────────────────┘

  ┌────────────────────────────────────┴────────────────┐
   create table users(id serial primary key, name text);

这是快速原型设计的最佳方法, 我们已经看到数十个团队和独立开发者成功地将其作为他们生产应用中的主要迁移流程。 它与蓝绿部署策略和无服务器数据库如 PlanetscaleNeonTurso 等非常契合。




drizzle-kit push 需要你指定 dialect、模式文件的路径, 并提供数据库连接的 urluser:password@host:port/db 参数, 你可以通过 drizzle.config.ts 配置文件或 CLI 选项提供它们:

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

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: {
    url: "postgresql://user:password@host:port/dbname",
  },
});
npx drizzle-kit push

模式文件路径

你可以有一个单独的 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",
});

项目中多个配置文件

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

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

指定数据库驱动

IMPORTANT

Expo SQLiteOP SQLite 是设备上的(每用户)数据库,无法在其中 push 迁移。
对于嵌入式数据库,Drizzle 提供了 嵌入式迁移 - 查看我们的 快速开始 指南。

Drizzle Kit 不包含预打包的数据库驱动, 它将根据当前项目的 dialect 自动选择可用的数据库驱动 - 查看讨论

大多数同一方言的驱动程序共享相同的连接参数, 至于像 aws-data-apipglightd1-http 的例外情况,你将需要显式指定 driver 参数。

AWS Data API
PGLite
Cloudflare D1 HTTP
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  driver: "aws-data-api",
  dbCredentials: {
    database: "database",
    resourceArn: "resourceArn",
    secretArn: "secretArn",
  },
};

包括表、模式和扩展

drizzle-kit push 默认管理 public 模式中的所有表。 你可以通过 tablesFiltersschemaFilterextensionFilters 选项配置表、模式和扩展的列表。

tablesFilter基于 glob 的表名过滤器,例如 ["users", "user_info"]"user*" 。默认是 "*"
schemaFilter模式名过滤器,例如 ["public", "drizzle"]。默认是 ["public"]
extensionsFilters已安装数据库扩展的列表,例如 ["postgis"]。默认是 []

让我们配置 drizzle-kit 只操作 public 模式中的 所有表, 并让 drizzle-kit 知道有一个安装的 postgis 扩展, 它会在 public 模式中创建自己的表,因此 drizzle 可以忽略它们。

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

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: {
    url: "postgresql://user:password@host:port/dbname",
  },
  extensionsFilters: ["postgis"],
  schemaFilter: ["public"],
  tablesFilter: ["*"],
});
npx drizzle-kit push

扩展的配置选项列表

drizzle-kit push 有一些仅限于 CLI 的选项

verbose执行前打印所有 SQL 语句
strict执行 SQL 语句前始终要求确认
force自动接受所有数据丢失的语句

npm
yarn
pnpm
bun
npx drizzle-kit push --strict --verbose --force



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

dialectrequired数据库方言,必须是 postgresql mysql sqlite turso
schemarequired指向 TypeScript 模式文件或包含多个模式文件的文件夹的路径
driver驱动程序例外 aws-data-api d1-http pglight
tablesFilter表名过滤器
schemaFilter模式名称过滤器。默认:["public"]
extensionsFilters数据库扩展内部数据库过滤器
url数据库连接字符串
user数据库用户
password数据库密码
host主机
port端口
database数据库名称
config配置文件路径,默认=drizzle.config.ts
npm
yarn
pnpm
bun
npx drizzle-kit push dialect=postgresql schema=src/schema.ts url=postgresql://user:password@host:port/dbname
npx drizzle-kit push dialect=postgresql schema=src/schema.ts driver=pglite url=database/
npx drizzle-kit push dialect=postgresql schema=src/schema.ts --tablesFilter=‘user*’ --extensionsFilters=postgis url=postgresql://user:password@host:port/dbname

扩展示例

让我们在项目中声明 drizzle 模式并通过 drizzle-kit push 命令将其推送到数据库

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

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: {
    url: "postgresql://user:password@host:port/dbname"
  },
});

现在让我们运行

npx drizzle-kit push

它将从数据库中拉取现有(空)模式,生成 SQL 迁移并在后台应用它

CREATE TABLE "users"(
  id serial primary key,
  name text,
)

完成 ✅