Drizzle Kit 配置文件

本指南假定您已熟悉：

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

Drizzle Kit 允许你在 TypeScript 或 JavaScript 配置文件中声明配置选项。

📦 <project root>
 ├ ...
 ├ 📂 drizzle
 ├ 📂 src
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

drizzle.config.ts

drizzle.config.js

import { defineConfig } from "drizzle-kit";

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

扩展配置文件示例

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  out: "./drizzle",
  dialect: "cockroach",
  schema: "./src/schema.ts",

  dbCredentials: {
    url: "./database/",
  },

  schemaFilter: "public",
  tablesFilter: "*",

  introspect: {
    casing: "camel",
  },

  migrations: {
    table: "__drizzle_migrations__",
    schema: "drizzle",
  },

  entities: {
    roles: {
      provider: '',
      exclude: [],
      include: []
    }
  },

  breakpoints: true,
  verbose: true,
});

Expand

多个配置文件

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

npm

yarn

pnpm

bun

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

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

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

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

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

migrations 文件夹

out 参数允许你定义迁移文件所在的文件夹，它是可选的，默认值为 drizzle。
当你在同一个项目中为不同数据库拥有许多独立的 schema，并希望为它们使用不同的迁移文件夹时，这非常有用。

Migration folder 包含带有 .sql 迁移文件的文件夹，这些文件会被 drizzle-kit 使用

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

import { defineConfig } from "drizzle-kit";

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

---

`dialect`

你正在使用的数据库方言


type	`postgresql` `mysql` `sqlite` `turso` `singlestore` `mssql` `cockroach`
default	—
commands	`generate`, `push`, `pull`, `studio`, `migrate`, `up`, `export`

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "cockroach", 
});

`schema`

glob 基于路径的 drizzle schema 文件或文件夹。


type	`string` `string[]`
default	—
commands	`generate`, `push`, `export`, `studio`

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

`out`

定义 SQL 迁移文件、schema 的 json 快照，以及 drizzle-kit pull 命令生成的 schema.ts 的输出文件夹。


type	`string` `string[]`
default	`drizzle`
commands	`generate`, `pull`, `migrate`, `check`, `up`

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  out: "./drizzle", 
});

---

`dbCredentials`

以 url、user:password@host:port/db 参数，或特定于方言驱动程序（aws-data-api d1-http pglite ）的连接选项形式提供的数据库连接凭据。


type	`postgresql` `mysql` `sqlite` `turso` `singlestore` `mssql` `cockroach`
default	—
commands	`push`, `pull`, `migrate`, `studio`

Connection string

Connection params

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "cockroach",
  dbCredentials: {
    url: "postgres://user:password@host:port/db",
  }
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "cockroach",
  dbCredentials: {
    host: "host",
    port: 26257,
    user: "user",
    password: "password",
    database: "dbname",
    ssl: true, // 可以是 boolean | "require" | "allow" | "prefer" | "verify-full" | 来自 node:tls 的选项
  }
});

`migrations`

运行 drizzle-kit migrate 时，drizzle 会将成功应用的迁移记录到数据库中名为 __drizzle_migrations、位于 drizzle schema 的日志表里。

migrations 配置选项可让你同时更改迁移日志的 table 名称和 schema。


type	`{ table: string, schema: string }`
default	`{ table: "__drizzle_migrations", schema: "drizzle" }`
commands	`migrate`, `push`, `pull`

export default defineConfig({
  dialect: "cockroach",
  schema: "./src/schema.ts",
  migrations: {
    table: 'my-migrations-table', // 默认为 `__drizzle_migrations`
    schema: 'my_schema', // 默认为 `drizzle`
  },
});

`introspect`

drizzle-kit pull 命令的配置。

casing 负责代码中列键的大小写形式


type	`{ casing: "preserve" \| "camel" }`
default	`{ casing: "camel" }`
commands	`pull`

camel

preserve

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

export const users = p.cockroachTable("users", {
  id: p.int4(),
  firstName: p.string("first-name"),
  lastName: p.string("LastName"),
  email: p.string(),
  phoneNumber: p.string("phone_number"),
});

SELECT column_name as column_name, lower(crdb_sql_type) as data_type FROM information_schema.columns WHERE table_name = 'users';

 column_name   | data_type        
---------------+------------------------
 id            | int4
 first-name    | string
 LastName      | string
 email         | string
 phone_number  | string

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

export const users = p.cockroachTable("users", {
  id: p.int4(),
  "first-name": p.string("first-name"),
  LastName: p.string("LastName"),
  email: p.string(),
  phone_number: p.string("phone_number"),
});

SELECT column_name as column_name, lower(crdb_sql_type) as data_type FROM information_schema.columns WHERE table_name = 'users';

 column_name   | data_type        
---------------+------------------------
 id            | int4
 first-name    | string
 LastName      | string
 email         | string
 phone_number  | string

---

`tablesFilter`

如果你想使用一个数据库运行多个项目 - 请查看我们的指南。

drizzle-kit push 和 drizzle-kit pull 默认会管理所有表。你可以通过 tablesFilters、schemaFilter 和 extensionFilters 选项配置表、模式和扩展的列表。

tablesFilter 选项允许你指定基于 glob 的表名过滤器，例如 ["users", "user_info"] 或 "user*"


type	`string` `string[]`
default	—
commands	`push` `pull`

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "cockroach",
  tablesFilter: ["users", "posts", "project1_*"],
});

`schemaFilter`

如果你想使用一个数据库运行多个项目 - 请查看我们的指南。

drizzle-kit push 和 drizzle-kit pull 默认会管理所有模式。

schemaFilter 选项允许你指定基于 glob 的模式名称过滤器，例如 ["public", "auth"] 或 "tenant_*"


type	`string[]`
commands	`push` `pull`

export default defineConfig({
  dialect: "cockroach",
  schemaFilter: ["public", "schema1", "schema2"],
});

---

`entities`

此配置用于为数据库中的特定 entities 设置管理选项。

目前，它只包含 roles，但最终所有数据库实体都会迁移到这里，例如 tables、schemas、extensions、functions、triggers 等。

`roles`

如果你使用 Drizzle Kit 来管理你的 schema，尤其是已定义的角色，那么有时会遇到一些未在 Drizzle schema 中定义的角色。在这种情况下，你可能希望 Drizzle Kit 跳过这些 roles，而不必在 Drizzle schema 中为每个 role 都写一遍并标记为 .existing()。

roles 选项可以让你：

启用或禁用 Drizzle Kit 的角色管理。
从 Drizzle Kit 的管理范围中排除特定角色。
将特定角色纳入 Drizzle Kit 的管理范围。
为 Neon 和 Supabase 等不会管理其特定角色的提供方启用模式。
组合以上所有选项


type	`boolean \| { provider: "neon" \| "supabase", include: string[], exclude: string[] }`
default	`false`
commands	`push` `pull`

默认情况下，drizzle-kit 不会为你管理 roles，因此你需要在 drizzle.config.ts 中启用它。

export default defineConfig({
  dialect: "cockroach",
  entities: {
    roles: true
  }
});

你有一个名为 admin 的 role，并希望将其从可管理 roles 列表中排除

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

export default defineConfig({
  ...
  entities: {
    roles: {
      exclude: ['admin']
    }
  }
});

你有一个名为 admin 的 role，并希望将其加入可管理 roles 列表

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

export default defineConfig({
  ...
  entities: {
    roles: {
      include: ['admin']
    }
  }
});

如果你正在使用 Neon，并且想排除由 Neon 定义的 roles，可以使用 provider 选项

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

export default defineConfig({
  ...
  entities: {
    roles: {
      provider: 'neon'
    }
  }
});

如果你正在使用 Supabase，并且想排除由 Supabase 定义的 roles，可以使用 provider 选项

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

export default defineConfig({
  ...
  entities: {
    roles: {
      provider: 'supabase'
    }
  }
});

重要

你可能会遇到这样的情况：Drizzle 相较于数据库提供方新指定的 roles 稍显滞后，因此你可能需要同时使用 provider 选项和 exclude 来排除额外的 roles。你可以很轻松地通过 Drizzle 实现：

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

export default defineConfig({
  ...
  entities: {
    roles: {
      provider: 'supabase',
      exclude: ['new_supabase_role']
    }
  }
});

---

`verbose`

在 drizzle-kit push 命令期间打印所有 SQL 语句。


type	`boolean`
default	`false`
commands	`pull`

export default defineConfig({
  dialect: "cockroach",
  verbose: false,
});

`breakpoints`

Drizzle Kit 会自动在生成的 SQL 迁移文件中嵌入 --> statement-breakpoint，
这对于不支持在一个事务中执行多个 DDL 交替语句的数据库是必要的（MySQL 和 SQLite）。

breakpoints 选项标志允许你将其开启或关闭


type	`boolean`
default	`true`
commands	`generate` `pull`

export default defineConfig({
  dialect: "cockroach",
  breakpoints: false,
});