`drizzle-kit push`

本指南假定您已熟悉：

开始使用 Drizzle 和 drizzle-kit - 请阅读这里
Drizzle schema 基础 - 请阅读这里
数据库连接基础 - 请阅读这里
Drizzle migrations 基础 - 请阅读这里
Drizzle Kit 概览和配置文件文档

drizzle-kit push 允许你直接将 schema 以及后续的 schema 变更真正推送到数据库，同时省略 SQL 文件的生成；它旨在覆盖 Drizzle migrations 的代码优先方法。

它是如何在底层工作的？

当你运行 Drizzle Kit 的 push 命令时，它会：

读取你的 Drizzle schema 文件，并构建 schema 的 JSON 快照
拉取（introspect）数据库 schema
根据两者之间的差异生成 SQL migrations
将 SQL migrations 应用到数据库

import * as p from "drizzle-orm/cockroach-core";

export const users = p.cockroachTable("users", {
  id: p.int4().primaryKey(),
  name: p.string(),
});

┌─────────────────────┐                  
│ ~ drizzle-kit push  │                  
└─┬───────────────────┘                  
  │                                           ┌──────────────────────────┐
  └ 拉取当前数据库 schema --------------------> │                          │
                                              │                          │
  ┌ 基于差异生成变更 <------------------------ │         DATABASE         │
  │                                           │                          │
  └ 将 migrations 应用到数据库 ---------------> │                          │
                                       │      └──────────────────────────┘
                                       │
  ┌───────────────────────────────────────────┴────────────────┐
   CREATE TABLE "users" ("id" int4 PRIMARY KEY, "name" string);

它是快速原型开发的最佳方式，我们已经看到许多团队和个人开发者成功地将其作为生产应用中的主要 migrations 流程。它与蓝绿部署策略以及无服务器数据库（如 Planetscale、Neon、Turso 等）配合得非常好。

drizzle-kit push 要求你指定 dialect、schema 文件路径，以及数据库连接的 url 或 user:password@host:port/db 参数，你可以通过 drizzle.config.ts 配置文件或通过 CLI 选项来提供它们：

使用配置文件

使用 CLI 选项

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

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

npx drizzle-kit push

npx drizzle-kit push --dialect=cockroach --schema=./src/schema.ts --url=postgresql://user:password@host:port/dbname

Schema 文件路径

你可以只有一个 schema.ts 文件，也可以在项目中分散放置任意多个 schema 文件。 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",
});

📦 <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
});

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

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

npm

yarn

pnpm

bun

npx drizzle-kit push --config=drizzle-dev.config.ts
npx drizzle-kit push --config=drizzle-prod.config.ts

yarn drizzle-kit push --config=drizzle-dev.config.ts
yarn drizzle-kit push --config=drizzle-prod.config.ts

pnpm drizzle-kit push --config=drizzle-dev.config.ts
pnpm drizzle-kit push --config=drizzle-prod.config.ts

bunx drizzle-kit push --config=drizzle-dev.config.ts
bunx drizzle-kit push --config=drizzle-prod.config.ts

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

指定数据库驱动

Drizzle Kit 不会自带预打包的数据库驱动，它会根据 dialect 自动从你当前项目中选择可用的数据库驱动 - 查看讨论.

包含表和 schema

drizzle-kit push 默认会管理所有表和 schema。你可以通过 tablesFilter 和 schemaFilter 选项配置表和 schema 的列表。


`tablesFilter`	基于 `glob` 的表名过滤器，例如 `["users", "user_info"]` 或 `"user"`。默认值是 `""`
`schemaFilter`	schema 名称过滤器，例如 `["public", "drizzle"]`。默认值是 `"*"`

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

import { defineConfig } from "drizzle-kit";

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

npx drizzle-kit push

扩展配置列表

drizzle-kit push 还有一组仅限 CLI 的选项


`verbose`	在执行前打印所有 SQL 语句
`explain`	打印计划中的 SQL 变更，但不实际应用它们（dry run）
`force`	自动接受所有会导致数据丢失的语句

npm

yarn

pnpm

bun

npx drizzle-kit push --explain --verbose --force

yarn drizzle-kit push --explain --verbose --force

pnpm drizzle-kit push --explain --verbose --force

bunx drizzle-kit push --explain --verbose --force

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


`dialect`	`required`	数据库方言，取值之一为 `postgresql` `mysql` `sqlite` `turso` `singlestore` `mssql` `cockroach`
`schema`	`required`	typescript schema 文件或包含多个 schema 文件的文件夹路径
`tablesFilter`		表名过滤器
`schemaFilter`		schema 名称过滤器。默认值：`["*"]`
`url`		数据库连接字符串
`user`		数据库用户
`password`		数据库密码
`host`		主机
`port`		端口
`database`		数据库名称
`config`		配置文件路径，默认=`drizzle.config.ts`

npm

yarn

pnpm

bun

npx drizzle-kit push dialect=cockroach schema=src/schema.ts url=postgresql://user:password@host:port/dbname
npx drizzle-kit push dialect=cockroach schema=src/schema.ts driver=pglite url=database/
npx drizzle-kit push dialect=cockroach schema=src/schema.ts --tablesFilter=‘user*’ url=postgresql://user:password@host:port/dbname

yarn drizzle-kit push dialect=cockroach schema=src/schema.ts url=postgresql://user:password@host:port/dbname
yarn drizzle-kit push dialect=cockroach schema=src/schema.ts driver=pglite url=database/
yarn drizzle-kit push dialect=cockroach schema=src/schema.ts --tablesFilter=‘user*’ url=postgresql://user:password@host:port/dbname

pnpm drizzle-kit push dialect=cockroach schema=src/schema.ts url=postgresql://user:password@host:port/dbname
pnpm drizzle-kit push dialect=cockroach schema=src/schema.ts driver=pglite url=database/
pnpm drizzle-kit push dialect=cockroach schema=src/schema.ts --tablesFilter=‘user*’ url=postgresql://user:password@host:port/dbname

bunx drizzle-kit push dialect=cockroach schema=src/schema.ts url=postgresql://user:password@host:port/dbname
bunx drizzle-kit push dialect=cockroach schema=src/schema.ts driver=pglite url=database/
bunx drizzle-kit push dialect=cockroach schema=src/schema.ts --tablesFilter=‘user*’ url=postgresql://user:password@host:port/dbname

扩展示例

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

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

drizzle.config.ts

src/schema.ts

import { defineConfig } from "drizzle-kit";

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

import * as p from "drizzle-orm/cockroach-core";

export const users = p.cockroachTable("users", {
  id: p.int4().primaryKey(),
  name: p.string(),
})

现在让我们运行

npx drizzle-kit push

它会从数据库中拉取现有的（空）schema，并在底层生成 SQL migration 然后应用它

CREATE TABLE "users" (
	"id" int4 PRIMARY KEY,
	"name" string
);

完成 ✅