Drizzle 마이그레이션 기본 개념

SQL 데이터베이스는 저장할 엔티티의 엄격한 스키마를 미리 정의해야 합니다.
이러한 엔티티의 구조를 변경해야 할 때는 스키마 마이그레이션을 통해 변경해야 합니다.

데이터베이스 마이그레이션을 관리하는 여러 가지 프로덕션 등급 방법이 있습니다.
Drizzle은 데이터베이스 우선 방식이든 코드베이스 우선 방식이든 상관없이 모든 방법에 완벽하게 적합하도록 설계되었습니다.

데이터베이스 우선 방식은 데이터베이스 스키마가 진리의 원천이 되는 방식입니다.
데이터베이스 스키마를 직접 데이터베이스에서 관리하거나 데이터베이스 마이그레이션 도구를 통해 관리한 다음,
데이터베이스 스키마를 코드베이스 애플리케이션 레벨의 엔티티로 가져옵니다.

코드베이스 우선 방식은 코드베이스의 데이터베이스 스키마가 진리의 원천이 되고 버전 관리가 되는 방식입니다.
JavaScript/TypeScript로 데이터베이스 스키마를 선언하고 관리한 다음,
Drizzle을 사용하거나 직접 또는 외부 마이그레이션 도구를 통해 데이터베이스에 해당 스키마를 적용합니다.

Drizzle가 어떻게 도울 수 있을까요?

drizzle-kit을 개발했습니다. 이는 Drizzle와 함께 마이그레이션을 관리하기 위한 CLI 앱입니다.

drizzle-kit migrate
drizzle-kit generate
drizzle-kit push
drizzle-kit pull

이 도구는 현재 비즈니스 요구에 따라 마이그레이션 방식을 선택할 수 있도록 설계되었습니다.

데이터베이스 우선 접근 방식과 코드베이스 우선 접근 방식 모두에 적합하며, 스키마를 푸시하거나 SQL 마이그레이션 파일을 생성하거나 데이터베이스에서 스키마를 풀할 수 있습니다. 혼자 작업하거나 팀과 함께 작업할 때 모두 적합합니다.

이제 프로젝트에 가장 적합한 옵션을 선택해 보세요:

옵션 1

외부 마이그레이션 도구를 사용하거나 데이터베이스에 직접 SQL 마이그레이션을 실행하여 데이터베이스 스키마를 직접 관리합니다. Drizzle에서는 데이터베이스에서 현재 스키마 상태를 가져와 TypeScript 스키마 파일로 저장하기만 하면 됩니다.

이것은 데이터베이스 우선 접근 방식입니다. 데이터베이스 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 데이터베이스 스키마를 TypeScript로 가져올 수 있습니다. drizzle-kit pull 명령을 사용하면 됩니다.

                                  ┌────────────────────────┐      ┌─────────────────────────┐ 
                                  │                        │ <---  CREATE TABLE "users" (
┌──────────────────────────┐      │                        │        "id" SERIAL PRIMARY KEY,
│ ~ drizzle-kit pull       │      │                        │        "name" TEXT,
└─┬────────────────────────┘      │        DATABASE        │        "email" TEXT UNIQUE
  │                               │                        │       );
  └ 데이터베이스 스키마 가져오기 -----> │                        │
  ┌ Drizzle 스키마 생성       <----- │                        │
  │ TypeScript 파일로 저장        └────────────────────────┘
  │
  v

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

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

옵션 2

데이터베이스 스키마를 TypeScript 코드베이스에 두고 싶습니다. SQL 마이그레이션 파일을 다루고 싶지 않습니다.
Drizzle가 스키마를 데이터베이스에 직접 “푸시”하도록 하고 싶습니다.

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 스키마 변경 사항을 데이터베이스에 푸시할 수 있습니다. drizzle-kit push 명령을 사용하면 됩니다.

이 방식은 빠른 프로토타이핑에 가장 적합하며, 많은 팀과 개인 개발자들이 프로덕션 애플리케이션에서 이 방식을 주요 마이그레이션 흐름으로 성공적으로 사용하고 있습니다.

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

export const users = p.pgTable("users", {
  id: p.serial().primaryKey(),
  name: p.text(),
  email: p.text().unique(), // <--- 컬럼 추가
};

`users` 테이블에 컬럼 추가                                                                          
┌──────────────────────────┐                  
│ + email: text().unique() │                  
└─┬────────────────────────┘                  
  │                                           
  v                                           
┌──────────────────────────┐                  
│ ~ drizzle-kit push       │                  
└─┬────────────────────────┘                  
  │                                           ┌──────────────────────────┐
  └ 현재 데이터베이스 스키마 가져오기 ---------> │                          │
                                              │                          │
  ┌ 차이점을 기반으로 변경 사항 생성 <---- │         DATABASE         │
  │                                           │                          │
  └ 데이터베이스에 마이그레이션 적용 -------> │                          │
                                       │      └──────────────────────────┘
                                       │
  ┌────────────────────────────────────┴──────────────┐
   ALTER TABLE `users` ADD COLUMN `email` TEXT UNIQUE;

옵션 3

데이터베이스 스키마를 TypeScript 코드베이스에 두고 싶습니다. Drizzle가 SQL 마이그레이션 파일을 생성하고 데이터베이스에 적용하도록 하고 싶습니다.

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 스키마 변경 사항을 기반으로 SQL 마이그레이션 파일을 생성할 수 있습니다. drizzle-kit generate 명령을 사용하면 됩니다. 그리고 drizzle-kit migrate 명령을 사용하여 데이터베이스에 적용할 수 있습니다.

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

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

┌────────────────────────┐                  
│ $ drizzle-kit generate │                  
└─┬──────────────────────┘                  
  │                                           
  └ 1. 이전 마이그레이션 폴더 읽기
    2. 현재와 이전 스키마의 차이점 찾기
    3. 필요한 경우 개발자에게 이름 변경 요청
  ┌ 4. SQL 마이그레이션 생성 및 파일로 저장
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 drizzle       
  │      └ 📂 20242409125510_premium_mister_fear
  │        ├ 📜 snapshot.json
  │        └ 📜 migration.sql
  v

-- drizzle/20242409125510_premium_mister_fear/migration.sql

CREATE TABLE "users" (
 "id" SERIAL PRIMARY KEY,
 "name" TEXT,
 "email" TEXT UNIQUE
);

┌───────────────────────┐                  
│ $ drizzle-kit migrate │                  
└─┬─────────────────────┘                  
  │                                                         ┌──────────────────────────┐                                         
  └ 1. 마이그레이션 폴더에서 migration.sql 파일 읽기        │                          │
    2. 데이터베이스에서 마이그레이션 기록 가져오기 -------------> │                          │
  ┌ 3. 이전에 적용되지 않은 마이그레이션 선택 <-------------- │         DATABASE         │
  └ 4. 새로운 마이그레이션을 데이터베이스에 적용 ---------------> │                          │
                                                            │                          │
                                                            └──────────────────────────┘
[✓] 완료!

옵션 4

데이터베이스 스키마를 TypeScript 코드베이스에 두고 싶습니다. Drizzle가 SQL 마이그레이션 파일을 생성하고, 런타임 중에 적용하도록 하고 싶습니다.

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 스키마 변경 사항을 기반으로 SQL 마이그레이션 파일을 생성할 수 있습니다. drizzle-kit generate 명령을 사용하면 됩니다. 그리고 애플리케이션 런타임 중에 데이터베이스에 적용할 수 있습니다.

이 방식은 모놀리식 애플리케이션에서 데이터베이스 마이그레이션을 다운타임 없이 배포하고, 문제가 발생하면 DDL 변경 사항을 롤백할 때 널리 사용됩니다. 또한 서버리스 배포에서도 사용되며, 배포 과정 중에 커스텀 리소스로 마이그레이션을 한 번 실행합니다.

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

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

┌────────────────────────┐                  
│ $ drizzle-kit generate │                  
└─┬──────────────────────┘                  
  │                                           
  └ 1. 이전 마이그레이션 폴더 읽기
    2. 현재와 이전 스키마의 차이점 찾기
    3. 필요한 경우 개발자에게 이름 변경 요청
  ┌ 4. SQL 마이그레이션 생성 및 파일로 저장
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 drizzle       
  │      └ 📂 20242409125510_premium_mister_fear
  │        ├ 📜 snapshot.json
  │        └ 📜 migration.sql
  v

-- drizzle/20242409125510_premium_mister_fear/migration.sql

CREATE TABLE "users" (
 "id" SERIAL PRIMARY KEY,
 "name" TEXT,
 "email" TEXT UNIQUE
);

// index.ts
import { drizzle } from "drizzle-orm/node-postgres"
import { migrate } from 'drizzle-orm/node-postgres/migrator';

const db = drizzle(process.env.DATABASE_URL);

await migrate(db);

┌───────────────────────┐                  
│ npx tsx src/index.ts  │                  
└─┬─────────────────────┘                  
  │                                                      
  ├ 1. 데이터베이스 연결 초기화                             ┌──────────────────────────┐                                         
  └ 2. 마이그레이션 폴더에서 migration.sql 파일 읽기        │                          │
    3. 데이터베이스에서 마이그레이션 기록 가져오기 -------------> │                          │
  ┌ 4. 이전에 적용되지 않은 마이그레이션 선택 <-------------- │         DATABASE         │
  └ 5. 새로운 마이그레이션을 데이터베이스에 적용 ---------------> │                          │
                                                            │                          │
                                                            └──────────────────────────┘
[✓] 완료!

옵션 5

데이터베이스 스키마를 TypeScript 코드베이스에 두고 싶습니다. Drizzle가 SQL 마이그레이션 파일을 생성하도록 하고 싶습니다. 하지만 직접 또는 외부 마이그레이션 도구를 통해 데이터베이스에 적용할 것입니다.

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 스키마 변경 사항을 기반으로 SQL 마이그레이션 파일을 생성할 수 있습니다. drizzle-kit generate 명령을 사용하면 됩니다. 그리고 직접 또는 외부 마이그레이션 도구를 통해 데이터베이스에 적용할 수 있습니다.

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

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

┌────────────────────────┐                  
│ $ drizzle-kit generate │                  
└─┬──────────────────────┘                  
  │                                           
  └ 1. 이전 마이그레이션 폴더 읽기
    2. 현재와 이전 스키마의 차이점 찾기
    3. 필요한 경우 개발자에게 이름 변경 요청
  ┌ 4. SQL 마이그레이션 생성 및 파일로 저장
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 drizzle       
  │      └ 📂 20242409125510_premium_mister_fear
  │        ├ 📜 snapshot.json
  │        └ 📜 migration.sql
  v

-- drizzle/20242409125510_premium_mister_fear/migration.sql

CREATE TABLE "users" (
 "id" SERIAL PRIMARY KEY,
 "name" TEXT,
 "email" TEXT UNIQUE
);

┌───────────────────────────────────┐                  
│ (._.) 이제 마이그레이션을 실행하세요 │           
└─┬─────────────────────────────────┘  
  │
 데이터베이스에 직접
  │                                         ┌────────────────────┐
  ├────────────────────────────────────┬───>│                    │  
  │                                    │    │      Database      │           
 또는 외부 도구를 통해                 │    │                    │   
  │                                    │    └────────────────────┘
  │  ┌────────────────────┐            │      
  └──│ Bytebase           ├────────────┘         
     ├────────────────────┤  
     │ Liquibase          │
     ├────────────────────┤ 
     │ Atlas              │
     ├────────────────────┤ 
     │ etc…               │
     └────────────────────┘

[✓] 완료!

옵션 6

데이터베이스 스키마를 TypeScript 코드베이스에 두고 싶습니다. Drizzle가 Drizzle 스키마의 SQL 표현을 콘솔에 출력하도록 하고 싶습니다. 그리고 Atlas를 통해 데이터베이스에 적용할 것입니다.

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 진리의 원천으로 두고, Drizzle를 사용하여 스키마 변경 사항을 기반으로 SQL 문을 내보낼 수 있습니다. drizzle-kit export 명령을 사용하면 됩니다. 그리고 외부 마이그레이션 도구를 통해 데이터베이스에 적용할 수 있습니다.

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

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

┌────────────────────────┐                  
│ $ drizzle-kit export   │                  
└─┬──────────────────────┘                  
  │                                           
  └ 1. Drizzle 스키마 읽기
    2. 스키마의 SQL 표현 생성
  ┌ 4. 콘솔에 출력
  │    
  │       
  │      
  │        
  │        
  v

CREATE TABLE "users" (
 "id" SERIAL PRIMARY KEY,
 "name" TEXT,
 "email" TEXT UNIQUE
);

┌───────────────────────────────────┐                  
│ (._.) 이제 마이그레이션을 실행하세요 │           
└─┬─────────────────────────────────┘  
  │
 Atlas를 통해
  │                                    ┌──────────────┐
  │  ┌────────────────────┐            │              │
  └──│ Atlas              ├───────────>│  Database    │      
     └────────────────────┘            │              │       
                                       └──────────────┘

[✓] 완료!