`drizzle-kit push`

This guide assumes familiarity with:

Drizzle와 drizzle-kit 시작하기 - 여기서 읽기
Drizzle 스키마 기본 개념 - 여기서 읽기
데이터베이스 연결 기본 - 여기서 읽기
Drizzle 마이그레이션 기본 - 여기서 읽기
Drizzle Kit 개요 및 설정 파일 문서

drizzle-kit push는 SQL 파일 생성을 생략하고 스키마와 스키마 변경 사항을 직접 데이터베이스에 적용할 수 있게 해줍니다. 이 기능은 Drizzle 마이그레이션의 코드 우선(code first) 접근 방식을 지원하기 위해 설계되었습니다.

내부 동작 원리

Drizzle Kit push 커맨드를 실행하면 다음과 같은 과정이 진행됩니다:

Drizzle 스키마 파일을 읽고 스키마의 JSON 스냅샷을 생성합니다.
데이터베이스 스키마를 가져옵니다(introspect).
두 스키마 간의 차이를 기반으로 SQL 마이그레이션을 생성합니다.
SQL 마이그레이션을 데이터베이스에 적용합니다.

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

export const users = p.pgTable("users", {
  id: p.serial().primaryKey(),
  name: p.text(),
});

┌─────────────────────┐                  
│ ~ drizzle-kit push  │                  
└─┬───────────────────┘                  
  │                                           ┌──────────────────────────┐
  └ 현재 데이터베이스 스키마 가져오기 ------> │                          │
                                              │                          │
  ┌ 차이점을 기반으로 변경 사항 생성 <------ │         DATABASE         │
  │                                           │                          │
  └ 데이터베이스에 마이그레이션 적용 -------> │                          │
                                       │      └──────────────────────────┘
                                       │
  ┌────────────────────────────────────┴────────────────┐
   create table users(id serial primary key, name text);

이 방법은 빠른 프로토타이핑에 가장 적합하며, 많은 팀과 개인 개발자들이 프로덕션 애플리케이션에서 주요 마이그레이션 흐름으로 사용하고 있습니다. 특히 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: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: {
    url: "postgresql://user:password@host:port/dbname",
  },
});

npx drizzle-kit push

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

스키마 파일 경로

여러분은 하나의 schema.ts 파일을 사용하거나, 프로젝트 전체에 걸쳐 원하는 만큼의 스키마 파일을 분산시켜 배치할 수 있습니다. Drizzle Kit은 이 파일들의 경로를 glob 형식으로 schema 설정 옵션에 지정하도록 요구합니다.

예제 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가 가장 좋아하는 방식
});

하나의 프로젝트에 여러 설정 파일 사용하기

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

npx drizzle-kit push --config=drizzle-dev.config.ts
npx 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-dev.config.ts와 drizzle-prod.config.ts라는 두 개의 설정 파일을 사용하여 개발 환경과 프로덕션 환경을 구분할 수 있습니다. 이를 통해 각 환경에 맞는 설정을 쉽게 관리할 수 있습니다.

데이터베이스 드라이버 지정하기

IMPORTANT

Expo SQLite와 OP SQLite는 기기 내(사용자별) 데이터베이스로, 마이그레이션을 push할 수 없습니다.
임베디드 데이터베이스의 경우 Drizzle에서 임베디드 마이그레이션을 제공합니다. 시작하기 가이드를 참고하세요.

Drizzle Kit은 사전에 번들링된 데이터베이스 드라이버를 포함하지 않습니다. 현재 프로젝트에서 사용 가능한 데이터베이스 드라이버를 dialect에 따라 자동으로 선택합니다. 토론 참고

대부분 동일한 dialect를 사용하는 드라이버들은 동일한 연결 파라미터 집합을 공유합니다. 단, aws-data-api, pglight, d1-http와 같은 예외적인 경우에는 driver 파라미터를 명시적으로 지정해야 합니다.

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

테이블, 스키마, 확장 기능 포함하기

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


`tablesFilter`	`glob` 기반 테이블 이름 필터, 예: `["users", "user_info"]` 또는 `"user"`. 기본값은 `""`
`schemaFilter`	스키마 이름 필터, 예: `["public", "drizzle"]`. 기본값은 `["public"]`
`extensionsFilters`	설치된 데이터베이스 확장 기능 목록, 예: `["postgis"]`. 기본값은 `[]`

public 스키마의 모든 테이블만 작업하고,
drizzle-kit에게 postgis 확장 기능이 설치되어 있다는 것을 알려줍니다.
이 확장 기능은 public 스키마에 자체 테이블을 생성하므로, drizzle이 이를 무시할 수 있도록 설정합니다.

import { defineConfig } from "drizzle-kit";

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

npx drizzle-kit push

확장된 설정 목록

drizzle-kit push 명령어는 CLI 전용 옵션을 제공합니다.


`verbose`	실행 전 모든 SQL 문장을 출력
`strict`	SQL 문장 실행 전 항상 승인 요청
`force`	데이터 손실이 발생할 수 있는 모든 문장 자동 승인

npm

yarn

pnpm

bun

npx drizzle-kit push --strict --verbose --force

yarn drizzle-kit push --strict --verbose --force

pnpm drizzle-kit push --strict --verbose --force

bun drizzle-kit push --strict --verbose --force

drizzle-kit 설정은 drizzle.config.ts 파일을 통해 구성하는 것을 권장합니다. 하지만 CI/CD 파이프라인 등에서 필요할 경우 CLI를 통해 모든 설정 옵션을 제공할 수도 있습니다.


`dialect`	`required`	데이터베이스 방언, `--- dialects: ['postgresql', 'mysql', 'sqlite', 'turso', 'singlestore'] --- {frontmatter.dialects.map(dialect => <><code>{dialect}</code> </>)}` 위 코드는 `frontmatter.dialects` 배열에 있는 각 데이터베이스 방언(dialect)을 순회하며 `<code>` 태그로 감싸고, 각 항목 뒤에 공백을 추가하는 코드입니다. 이렇게 하면 각 방언 이름이 코드 형식으로 표시되고, 항목 사이에 공백이 생깁니다. 중 하나
`schema`	`required`	타입스크립트 스키마 파일 경로 또는 여러 스키마 파일이 있는 폴더 경로
`driver`		드라이버 예외 `drivers: ['aws-data-api', 'd1-http', 'pglight']` `{frontmatter.drivers.map((driver) => <><code>{driver}</code> </>)}` 위 코드는 `drivers` 배열에 있는 각 드라이버를 순회하며, 각 드라이버 이름을 `<code>` 태그로 감싸서 출력합니다. ` `는 공백 문자를 나타내며, 각 드라이버 이름 사이에 공백을 추가합니다.
`tablesFilter`		테이블 이름 필터
`schemaFilter`		스키마 이름 필터. 기본값: `["public"]`
`extensionsFilters`		데이터베이스 확장 기능 내부 필터
`url`		데이터베이스 연결 문자열
`user`		데이터베이스 사용자
`password`		데이터베이스 비밀번호
`host`		호스트
`port`		포트
`database`		데이터베이스 이름
`config`		설정 파일 경로, 기본값=`drizzle.config.ts`

npm

yarn

pnpm

bun

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

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

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

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

확장 예제

프로젝트에 Drizzle 스키마를 선언하고 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: "postgresql",
  schema: "./src/schema.ts",
  dbCredentials: {
    url: "postgresql://user:password@host:port/dbname"
  },
});

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

export const users = p.pgTable("users", {
  id: p.serial().primaryKey(),
  name: p.text(),
})

이제 다음 커맨드를 실행합니다.

npx drizzle-kit push

이 명령어는 데이터베이스에서 기존(비어 있는) 스키마를 가져와 SQL 마이그레이션을 생성하고 내부적으로 적용합니다.

CREATE TABLE "users"(
  id serial primary key,
  name text,
)

완료 ✅