Drizzle Kit 설정 파일

This guide assumes familiarity with:

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

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

마이그레이션 폴더

out 파라미터를 사용하면 마이그레이션 폴더를 정의할 수 있으며, 선택 사항이며 기본값은 drizzle입니다. 동일한 프로젝트에서 서로 다른 데이터베이스에 대해 많은 별도 스키마를 가질 수 있고, 각각에 대해 다른 마이그레이션 폴더를 가질 수 있으므로 매우 유용합니다.

마이그레이션 폴더에는 drizzle-kit에서 사용하는 .sql 마이그레이션 파일이 포함된 폴더가 포함됩니다

📦 <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: "postgresql", // "mysql" | "sqlite" | "postgresql" | "turso" | "singlestore" | "mssql"
  schema: "./src/schema/*",
  out: "./drizzle",
});

---

`dialect`

사용 중인 데이터베이스의 방언(Dialect)


type	`postgresql` `mysql` `sqlite` `turso` `singlestore` `mssql` `cockroachdb`
default	—
commands	`generate` `migrate` `push` `pull` `check` `up`

import { defineConfig } from "drizzle-kit";

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

`schema`

Drizzle 스키마 파일 또는 스키마 파일이 포함된 폴더에 대한 glob 기반 경로


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

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 마이그레이션 파일, 스키마의 JSON 스냅샷, 그리고 drizzle-kit pull 명령에서 생성되는 schema.ts의 출력 폴더를 정의합니다.


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

import { defineConfig } from "drizzle-kit";

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

`driver`

Drizzle Kit은 제공된 dialect를 기반으로 현재 프로젝트에서 사용 가능한 데이터베이스 드라이버를 자동으로 선택합니다. 하지만 일부 벤더 특정 데이터베이스는 다른 연결 파라미터 세트를 필요로 합니다.

driver 옵션을 사용하면 이러한 예외 드라이버를 명시적으로 선택할 수 있습니다.


type	`aws-data-api` `d1-http` `pglight`
default	—
commands	`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 )별 연결 옵션 형식의 데이터베이스 연결 자격 증명


type	union of drivers connection options
default	—
commands	`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: "mysql://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은 성공적으로 적용된 마이그레이션에 대한 기록을 public 스키마(PostgreSQL만 해당)의 __drizzle_migrations라는 로그 테이블에 저장합니다.

migrations 설정 옵션을 사용하면 마이그레이션 로그 table 이름과 schema를 모두 변경할 수 있습니다.


type	`{ table: string, schema: string }`
default	`{ table: "__drizzle_migrations", schema: "drizzle" }`
commands	`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은 코드 내 컬럼 키의 대소문자 처리 방식을 결정합니다.


type	`{ casing: "preserve" \| "camel" }`
default	`{ casing: "camel" }`
commands	`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*"


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

import { defineConfig } from "drizzle-kit";

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

`schemaFilter`

1.0.0-beta.1 버전부터 변경되었습니다!

IMPORTANT

0.x 버전에서의 작동 방식

schemaFilter 옵션을 사용하면 Drizzle Kit이 관리할 스키마 목록을 지정할 수 있습니다.


type	`string[]`
default	`["public"]`
commands	`push` `pull`

하나의 데이터베이스로 여러 프로젝트를 실행하려면 가이드를 확인하세요.

drizzle-kit push와 drizzle-kit pull은 기본적으로 모든 스키마를 관리합니다.

schemaFilter 옵션을 사용하면 glob 기반 스키마 이름 필터를 지정할 수 있습니다. 예: ["public", "auth"] 또는 "tenant_*"


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

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

`extensionsFilters`

postgis와 같은 일부 익스텐션은 데이터베이스에 설치될 때 public 스키마에 자체 테이블을 생성합니다. 이러한 테이블은 drizzle-kit push 또는 drizzle-kit pull에서 무시되어야 합니다.

extensionsFilters 옵션을 사용하면 Drizzle Kit이 스키마에서 해당 테이블을 무시하도록 설치된 익스텐션 목록을 선언할 수 있습니다.


type	`["postgis"]`
default	`[]`
commands	`push` `pull`

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

---

`entities`

이 설정은 데이터베이스의 특정 entities에 대한 관리 설정을 구성하기 위해 만들어졌습니다.

현재는 roles만 포함하지만, 결국 tables, schemas, extensions, functions, triggers 등 모든 데이터베이스 엔티티가 여기로 이동할 예정입니다.

`roles`

Drizzle Kit을 사용하여 스키마, 특히 정의된 역할(roles)을 관리하는 경우, Drizzle 스키마에 정의되지 않은 역할이 있는 상황이 발생할 수 있습니다. 이러한 경우, Drizzle 스키마에 각 역할을 작성하고 .existing()으로 표시할 필요 없이 Drizzle Kit이 해당 roles를 건너뛰도록 할 수 있습니다.

roles 옵션을 사용하면:

Drizzle Kit으로 역할 관리를 활성화하거나 비활성화할 수 있습니다.
Drizzle Kit의 관리에서 특정 역할을 제외할 수 있습니다.
Drizzle Kit의 관리를 위해 특정 역할을 포함할 수 있습니다.
특정 역할을 관리하지 않는 Neon 및 Supabase와 같은 프로바이더에 대한 모드를 활성화할 수 있습니다.
위의 모든 옵션을 결합할 수 있습니다.


type	`boolean \| { provider: "neon" \| "supabase", include: string[], exclude: string[]}`
default	`false`
commands	`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 문을 실행할지 확인하는 프롬프트를 표시합니다.


type	`boolean`
default	`false`
commands	`push`

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

`verbose`

drizzle-kit push 명령 중 모든 SQL 문을 출력합니다.


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

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

`breakpoints`

Drizzle Kit은 생성된 SQL 마이그레이션 파일에 --> statement-breakpoint를 자동으로 삽입합니다. 이는 하나의 트랜잭션에서 여러 DDL 변경 문을 지원하지 않는 데이터베이스(MySQL 및 SQLite)에 필요합니다.

breakpoints 옵션 플래그를 사용하면 이를 켜거나 끌 수 있습니다.


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

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