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

여러 개의 설정 파일 사용하기

프로젝트에서 여러 개의 설정 파일을 사용할 수 있습니다. 이는 여러 데이터베이스 단계나 여러 데이터베이스, 또는 동일한 프로젝트 내에서 다른 데이터베이스를 사용할 때 매우 유용합니다.

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

이 구조에서는 drizzle-dev.config.ts와 drizzle-prod.config.ts 두 개의 설정 파일을 사용하여 개발 환경과 프로덕션 환경에 각각 다른 설정을 적용할 수 있습니다.

마이그레이션 폴더

out 파라미터를 사용하면 마이그레이션 파일을 저장할 폴더를 지정할 수 있습니다. 이 파라미터는 선택 사항이며, 기본값은 drizzle입니다.
이 기능은 동일한 프로젝트 내에서 여러 데이터베이스에 대한 별도의 스키마를 가질 때 매우 유용합니다. 각 데이터베이스마다 다른 마이그레이션 폴더를 지정할 수 있기 때문입니다.

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

📦 <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`

사용 중인 데이터베이스의 방언(dialect)을 설정합니다.


타입	`<Dialects/>`
기본값	—
커맨드	`generate` `migrate` `push` `pull` `check` `up`

import { defineConfig } from "drizzle-kit";

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

`schema`

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",
  // 또는
  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가 가장 좋아하는 방식
});

`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 옵션을 사용하면 이러한 예외적인 드라이버를 명시적으로 선택할 수 있습니다.


타입	`drivers: ['aws-data-api', 'd1-http', 'pglight']` `{frontmatter.drivers.map((driver) => <><code>{driver}</code> </>)}` 위 코드는 `drivers` 배열에 있는 각 드라이버를 순회하며, 각 드라이버 이름을 `<code>` 태그로 감싸서 출력합니다. ` `는 공백 문자를 나타내며, 각 드라이버 이름 사이에 공백을 추가합니다.
기본값	—
명령어	`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: {
    // 메모리 내 데이터베이스
    url: ":memory:"
    
    // 또는 데이터베이스 폴더
    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 파라미터, 또는 드라이버별 연결 옵션으로 제공합니다.


타입	드라이버별 연결 옵션의 유니온 타입
기본값	—
사용 가능한 커맨드	`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'

// 연결 파라미터를 통해 설정
export default defineConfig({
  dialect: "postgresql",
  dbCredentials: {
    host: "host",
    port: 5432,
    user: "user",
    password: "password",
    database: "dbname",
    ssl: true, // boolean | "require" | "allow" | "prefer" | "verify-full" | 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'

// 연결 파라미터를 통해 설정
export default defineConfig({
  dialect: "mysql",
  dbCredentials: {
    host: "host",
    port: 5432,
    user: "user",
    password: "password",
    database: "dbname",
    ssl: "...", // string | SslOptions (mysql2 패키지의 ssl 옵션)
  }
})

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "sqlite",
  dbCredentials: {
    url: ":memory:", // 메모리 내 데이터베이스
    // 또는
    url: "sqlite.db", 
    // 또는
    url: "file:sqlite.db" // libsql에서 file: 접두사 필요
  }
})

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  dialect: "turso",
  dbCredentials: {
    url: "libsql://acme.turso.io" // 원격 Turso 데이터베이스 URL
    authToken: "...",

    // 로컬 데이터베이스가 필요한 경우

    url: ":memory:", // 메모리 내 데이터베이스
    // 또는
    url: "file:sqlite.db", // libsql에서 file: 접두사 필요
  }
})

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/", // 데이터베이스 폴더 경로
  }
})

`migrations`

drizzle-kit migrate 명령어를 실행하면, Drizzle은 성공적으로 적용된 마이그레이션에 대한 기록을 데이터베이스에 저장합니다. 이 기록은 PostgreSQL의 경우 public 스키마에 있는 __drizzle_migrations라는 로그 테이블에 저장됩니다.

migrations 설정 옵션을 사용하면 마이그레이션 로그 테이블의 이름과 스키마를 변경할 수 있습니다.


타입	`{ 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`
    schema: 'public', // PostgreSQL에서만 사용되며, 기본값은 `drizzle`
  },
});

`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`

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

drizzle-kit push와 drizzle-kit pull은 기본적으로 public 스키마의 모든 테이블을 관리합니다.
tablesFilters, schemaFilter, extensionFilters 옵션을 통해 테이블, 스키마, 확장 기능 목록을 설정할 수 있습니다.

schemaFilter 옵션은 Drizzle Kit이 관리할 스키마 목록을 지정할 수 있게 해줍니다.


타입	`string[]`
기본값	`["public"]`
명령어	`generate`, `push`, `pull`

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

`extensionsFilters`

postgis와 같은 일부 확장 기능은 데이터베이스에 설치될 때, 공개 스키마(public schema)에 자체 테이블을 생성합니다. 이러한 테이블은 drizzle-kit push나 drizzle-kit pull에서 무시되어야 합니다.

extensionsFilters 옵션을 사용하면, 설치된 확장 기능 목록을 선언하여 스키마에서 해당 테이블을 무시하도록 설정할 수 있습니다.


타입	`["postgis"]`
기본값	`[]`
지원 커맨드	`push` `pull`

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

---

`entities`

이 설정은 데이터베이스 내 특정 엔티티(entities)를 관리하기 위한 설정을 구성하는 데 사용됩니다.

현재는 역할(roles)만 포함되어 있지만, 앞으로 테이블(tables), 스키마(schemas), 확장 기능(extensions), 함수(functions), 트리거(triggers) 등 모든 데이터베이스 엔티티가 이곳으로 이전될 예정입니다.

`roles`

Drizzle Kit을 사용해 스키마와 특히 정의된 역할(roles)을 관리할 때, Drizzle 스키마에 정의되지 않은 역할이 있을 수 있습니다. 이런 경우, Drizzle Kit이 해당 역할을 건너뛰도록 설정할 수 있습니다. 이렇게 하면 각 역할을 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",
  extensionsFilters: 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에서 정의한 역할을 제외하려는 경우

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

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

Supabase를 사용 중이고, Supabase에서 정의한 역할을 제외하려는 경우

// 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",
  breakpoints: false,
});

`verbose`

drizzle-kit push 명령어 실행 시 모든 SQL 문을 출력합니다.


타입	`boolean`
기본값	`true`
명령어	`generate` `pull`

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

`breakpoints`

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

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


타입	`boolean`
기본값	`true`
명령어	`generate`, `pull`

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