Drizzle Kit 配置文件

本指南假定您熟悉

Drizzle 和 drizzle-kit 入门 - 在此阅读
Drizzle 模式基础 - 在此阅读
数据库连接基础 - 在此阅读
Drizzle 迁移基础 - 在此阅读
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: "postgresql",
  schema: "./src/schema.ts",
  out: "./drizzle",
});

扩展配置文件的示例

import { defineConfig } from "drizzle-kit";

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

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

  extensionsFilters: ["postgis"],
  schemaFilter: "public",
  tablesFilter: "*",

  introspect: {
    casing: "camel",
  },

  migrations: {
    prefix: "timestamp",
    table: "__drizzle_migrations__",
    schema: "public",
  },

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

  breakpoints: true,
  strict: true,
  verbose: true,
});

展开

多配置文件

您可以在项目中拥有多个配置文件，这在您有多个数据库阶段、多个数据库或同一项目中有不同的数据库时非常有用。

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

bun drizzle-kit generate --config=drizzle-dev.config.ts
bun 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

迁移文件夹

out 参数允许您定义迁移文件夹，它是可选的，默认为 drizzle。
这非常有用，因为您可以在同一个项目中为不同的数据库设置多个独立的模式，并为它们设置不同的迁移文件夹。

迁移文件夹包含 .sql 迁移文件和 _meta 文件夹，该文件夹由 drizzle-kit 使用

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

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql", // "mysql" | "sqlite" | "postgresql" | "turso" | "singlestore"
  schema: "./src/schema/*",
  out: "./drizzle",
});

---

`dialect`

您正在使用的数据库方言


类型	`postgresql` `mysql` `sqlite` `turso` `singlestore`
默认	—
命令	`generate` `migrate` `push` `pull` `check` `up`

import { defineConfig } from "drizzle-kit";

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

`schema`

glob 基于 glob 的 Drizzle 模式文件路径或包含模式文件的文件夹路径。


类型	`string` `string[]`
默认	—
命令	`generate` `push`

示例 1

示例 2

示例 3

示例 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 迁移文件、模式 JSON 快照以及来自 drizzle-kit pull 命令生成的 schema.ts 文件的输出文件夹。


类型	`string` `string[]`
默认	`drizzle`
命令	`generate` `migrate` `push` `pull` `check` `up`

import { defineConfig } from "drizzle-kit";

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

`driver`

Drizzle Kit 会根据提供的 dialect 自动从您的当前项目中选择可用的数据库驱动，但某些特定供应商的数据库需要不同的连接参数子集。

driver 选项允许您明确选择这些特殊驱动。


类型	`aws-data-api` `d1-http` `pglight`
默认	—
命令	`migrate` `push` `pull`

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

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  driver: "pglite",
  dbCredentials: {
    // inmemory
    url: ":memory:"
    
    // or database folder
    url: "./database/"
  },
});

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "sqlite",
  schema: "./src/schema.ts",
  driver: "d1-http",
  dbCredentials: {
    accountId: "accountId",
    databaseId: "databaseId",
    token: "token",
  },
});

---

`dbCredentials`

数据库连接凭据，可以是 url、user:password@host:port/db 参数的形式，或者特殊驱动（aws-data-api d1-http pglight）特定的连接选项。


类型	驱动连接选项的联合类型
默认	—
命令	`migrate` `push` `pull`

PostgreSQL

MySQL

SQLite

Turso

Cloudflare D1

AWS Data API

PGLite

import { defineConfig } from 'drizzle-kit'

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

import { defineConfig } from 'drizzle-kit'

// via connection params
export default defineConfig({
  dialect: "postgresql",
  dbCredentials: {
    host: "host",
    port: 5432,
    user: "user",
    password: "password",
    database: "dbname",
    ssl: true, // can be boolean | "require" | "allow" | "prefer" | "verify-full" | options from node:tls
  }
});

import { defineConfig } from 'drizzle-kit'

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

import { defineConfig } from 'drizzle-kit'

// via connection params
export default defineConfig({
  dialect: "mysql",
  dbCredentials: {
    host: "host",
    port: 5432,
    user: "user",
    password: "password",
    database: "dbname",
    ssl: "...", // can be: string | SslOptions (ssl options from mysql2 package)
  }
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "sqlite",
  dbCredentials: {
    url: ":memory:", // inmemory database
    // or
    url: "sqlite.db", 
    // or
    url: "file:sqlite.db" // file: prefix is required by libsql
  }
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "turso",
  dbCredentials: {
    url: "libsql://acme.turso.io" // remote Turso database url
    authToken: "...",

    // or if you need local db

    url: ":memory:", // inmemory database
    // or
    url: "file:sqlite.db", // file: prefix is required by libsql
  }
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "sqlite",
  driver: "d1-http",
  dbCredentials: {
    accountId: "",
    databaseId: "",
    token: "",
  }
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "postgresql",
  driver: "aws-data-api",
  dbCredentials: {
    database: "database",
    resourceArn: "resourceArn",
    secretArn: "secretArn",
  },
});

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "postgresql",
  driver: "pglite",
  dbCredentials: {
    url: "./database/", // database folder path
  }
});

`migrations`

当运行 drizzle-kit migrate 时，Drizzle 会将成功应用的迁移记录在您数据库的日志表 __drizzle_migrations 中，该表位于 public 模式（仅限 PostgreSQL）。

migrations 配置选项允许您更改迁移日志的 table 名称和 schema。


类型	`{ table: string, schema: string }`
默认	`{ table: "__drizzle_migrations", schema: "drizzle" }`
命令	`migrate`

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/schema.ts",
  migrations: {
    table: 'my-migrations-table', // `__drizzle_migrations` by default
    schema: 'public', // used in PostgreSQL only, `drizzle` by default
  },
});

`introspect`

drizzle-kit pull 命令的配置。

casing 负责代码中列键的命名规范


类型	`{ casing: "preserve" \| "camel" }`
默认	`{ casing: "camel" }`
命令	`pull`

camel

preserve

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

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

SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) as data_type FROM pg_catalog.pg_attribute a;

 column_name   | data_type        
---------------+------------------------
 id            | serial
 first-name    | text
 LastName      | text
 email         | text
 phone_number  | text

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

export const users = p.pgTable("users", {
  id: p.serial(),
  "first-name": p.text("first-name"),
  LastName: p.text("LastName"),
  email: p.text(),
  phone_number: p.text("phone_number"),
});

SELECT a.attname AS column_name, format_type(a.atttypid, a.atttypmod) as data_type FROM pg_catalog.pg_attribute a;

 column_name   | data_type        
---------------+------------------------
 id            | serial
 first-name    | text
 LastName      | text
 email         | text
 phone_number  | text

---

`tablesFilter`

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

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

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


类型	`string` `string[]`
默认	—
命令	`generate` `push` `pull`

import { defineConfig } from "drizzle-kit";

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

`schemaFilter`

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

schemaFilter 选项允许您指定 Drizzle Kit 要管理的模式列表


类型	`string[]`
默认	`["public"]`
命令	`push` `pull`

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

`extensionsFilters`

某些扩展，例如 postgis，在数据库上安装后，会在公共模式中创建自己的表。这些表必须被 drizzle-kit push 或 drizzle-kit pull 忽略。

extensionsFilters 选项允许您声明已安装扩展的列表，以便 drizzle kit 在模式中忽略其表。


类型	`["postgis"]`
默认	`[]`
命令	`push` `pull`

export default defineConfig({
  dialect: "postgresql",
  extensionsFilters: ["postgis"],
});

---

`entities`

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

目前，它仅包含 roles，但最终所有数据库实体都将迁移到此处，例如 tables、schemas、extensions、functions、triggers 等。

`roles`

如果您使用 Drizzle Kit 管理您的模式，尤其是定义的角色，则可能会出现某些角色未在 Drizzle 模式中定义的情况。在这种情况下，您可能希望 Drizzle Kit 跳过这些 roles，而无需在 Drizzle 模式中写入每个角色并将其标记为 .existing()。

roles 选项允许您

启用或禁用 Drizzle Kit 的角色管理功能。
将特定角色排除在 Drizzle Kit 的管理之外。
将特定角色纳入 Drizzle Kit 的管理范围。
为 Neon 和 Supabase 等不管理其特定角色的提供商启用模式。
结合上述所有选项


类型	`boolean \| { provider: "neon" \| "supabase", include: string[], exclude: string[]}`
默认	`false`
命令	`push` `pull` `generate`

默认情况下，drizzle-kit 不会为您管理角色，因此您需要在 drizzle.config.ts 中启用此功能。

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

您有一个名为 admin 的角色，并希望将其从可管理角色列表中排除

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

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

您有一个名为 admin 的角色，并希望将其包含到可管理角色列表中

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

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

如果您正在使用 Neon 并希望排除 Neon 定义的角色，可以使用 provider 选项

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

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

如果您正在使用 Supabase 并希望排除 Supabase 定义的角色，可以使用 provider 选项

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

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

重要提示

您可能会遇到 Drizzle 相对于数据库提供商指定的新角色略有滞后的情况，因此您可能需要同时使用 provider 选项和 exclude 附加角色。使用 Drizzle 可以轻松做到这一点。

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

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

---

`strict`

在运行 drizzle-kit push 命令时，提示确认是否运行打印的 SQL 语句。


类型	`boolean`
默认	`false`
命令	`push`

export default defineConfig({
  dialect: "postgresql",
  strict: false,
});

`verbose`

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


类型	`boolean`
默认	`true`
命令	`generate` `pull`

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

`breakpoints`

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

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


类型	`boolean`
默认	`true`
命令	`generate` `pull`

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