Drizzle 마이그레이션 기초

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

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

데이터베이스 우선은 데이터베이스 스키마가 소스 오브 트루스(source of truth)인 방식입니다. 데이터베이스에서 직접 또는 데이터베이스 마이그레이션 도구를 통해 데이터베이스 스키마를 관리한 다음, 데이터베이스 스키마를 코드베이스의 애플리케이션 레벨 엔티티로 가져옵니다.

코드베이스 우선은 코드베이스의 데이터베이스 스키마가 소스 오브 트루스이며 버전 관리 대상인 방식입니다. JavaScript/TypeScript로 데이터베이스 스키마를 선언하고 관리한 다음, Drizzle을 통해 직접 또는 외부 마이그레이션 도구를 통해 해당 스키마를 데이터베이스에 적용합니다.

Drizzle이 어떻게 도울 수 있나요?

Drizzle에서는 마이그레이션 관리를 위한 CLI 앱인 drizzle-kit을 제공합니다.

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

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

데이터베이스 우선 및 코드베이스 우선 접근 방식 모두에 적합하며, 스키마 푸시, SQL 마이그레이션 파일 생성 또는 데이터베이스에서 스키마 풀 기능을 제공합니다. 혼자 작업하든 팀으로 작업하든 완벽하게 활용할 수 있습니다.

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

옵션 1

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

세부사항 펼치기

이것은 데이터베이스 우선 접근 방식입니다. 데이터베이스 스키마를 소스 오브 트루스로 사용하며, Drizzle을 통해 drizzle-kit pull 명령으로 데이터베이스 스키마를 TypeScript로 가져올 수 있습니다.

                                  ┌────────────────────────┐      ┌─────────────────────────┐ 
                                  │                        │ <---  CREATE TABLE "users" (
┌──────────────────────────┐      │                        │        "id" SERIAL PRIMARY KEY,
│ ~ drizzle-kit pull       │      │                        │        "name" TEXT,
└─┬────────────────────────┘      │        DATABASE        │        "email" TEXT UNIQUE
  │                               │                        │       );
  └ Pull datatabase schema -----> │                        │
  ┌ Generate Drizzle       <----- │                        │
  │ schema TypeScript file        └────────────────────────┘
  │
  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(), // <--- added column
});

Add column to `users` table                                                                          
┌──────────────────────────┐                  
│ + email: text().unique() │                  
└─┬────────────────────────┘                  
  │                                           
  v                                           
┌──────────────────────────┐                  
│ ~ drizzle-kit push       │                  
└─┬────────────────────────┘                  
  │                                           ┌──────────────────────────┐
  └ Pull current datatabase schema ---------> │                          │
                                              │                          │
  ┌ Generate alternations based on diff <---- │         DATABASE         │
  │                                           │                          │
  └ Apply migrations to the database -------> │                          │
                                       │      └──────────────────────────┘
                                       │
  ┌────────────────────────────────────┴──────────────┐
   ALTER TABLE `users` ADD COLUMN `email` TEXT UNIQUE;

옵션 3

TypeScript 코드베이스에 데이터베이스 스키마를 두고 싶고, Drizzle이 SQL 마이그레이션 파일을 생성하고 데이터베이스에 적용하기를 원합니다

세부사항 펼치기

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 소스 오브 트루스로 사용하며, Drizzle을 통해 drizzle-kit generate 명령으로 스키마 변경사항을 기반으로 SQL 마이그레이션 파일을 생성하고, 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. read previous migration folders
    2. find diff between current and previous schema
    3. prompt developer for renames if necessary
  ┌ 4. generate SQL migration and persist to file
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 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. read migration.sql files in migrations folder        │                          │
    2. fetch migration history from database -------------> │                          │
  ┌ 3. pick previously unapplied migrations <-------------- │         DATABASE         │
  └ 4. apply new migration to the database ---------------> │                          │
                                                            │                          │
                                                            └──────────────────────────┘
[✓] done!

옵션 4

TypeScript 코드베이스에 데이터베이스 스키마를 두고 싶고, Drizzle이 SQL 마이그레이션 파일을 생성하고 런타임에 적용하기를 원합니다

세부사항 펼치기

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 소스 오브 트루스로 사용하며, Drizzle을 통해 drizzle-kit generate 명령으로 스키마 변경사항을 기반으로 SQL 마이그레이션 파일을 생성한 다음, 애플리케이션 런타임에 데이터베이스에 적용할 수 있습니다.

이 접근 방식은 무중단 배포 중에 데이터베이스 마이그레이션을 적용하고 문제가 발생하면 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. read previous migration folders
    2. find diff between current and previous schema
    3. prompt developer for renames if necessary
  ┌ 4. generate SQL migration and persist to file
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 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. init database connection                             ┌──────────────────────────┐                                         
  └ 2. read migration.sql files in migrations folder        │                          │
    3. fetch migration history from database -------------> │                          │
  ┌ 4. pick previously unapplied migrations <-------------- │         DATABASE         │
  └ 5. apply new migration to the database ---------------> │                          │
                                                            │                          │
                                                            └──────────────────────────┘
[✓] done!

옵션 5

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

세부사항 펼치기

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 소스 오브 트루스로 사용하며, Drizzle을 통해 drizzle-kit generate 명령으로 스키마 변경사항을 기반으로 SQL 마이그레이션 파일을 생성한 다음, 데이터베이스에 직접 또는 외부 마이그레이션 도구를 통해 적용할 수 있습니다.

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. read previous migration folders
    2. find diff between current and previous scheama
    3. prompt developer for renames if necessary
  ┌ 4. generate SQL migration and persist to file
  │    ┌─┴───────────────────────────────────────┐  
  │      📂 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
);

┌───────────────────────────────────┐                  
│ (._.) now you run your migrations │           
└─┬─────────────────────────────────┘  
  │
 directly to the database
  │                                         ┌────────────────────┐
  ├────────────────────────────────────┬───>│                    │  
  │                                    │    │      Database      │           
 or via external tools                 │    │                    │   
  │                                    │    └────────────────────┘
  │  ┌────────────────────┐            │      
  └──│ Bytebase           ├────────────┘         
     ├────────────────────┤  
     │ Liquibase          │
     ├────────────────────┤ 
     │ Atlas              │
     ├────────────────────┤ 
     │ etc…               │
     └────────────────────┘

[✓] done!

옵션 6

TypeScript 코드베이스에 데이터베이스 스키마를 두고 싶고, Drizzle이 Drizzle 스키마의 SQL 표현을 콘솔에 출력하기를 원하며, Atlas를 통해 데이터베이스에 적용하겠습니다

세부사항 펼치기

이것은 코드베이스 우선 접근 방식입니다. TypeScript Drizzle 스키마를 소스 오브 트루스로 사용하며, Drizzle을 통해 drizzle-kit export 명령으로 스키마 변경사항을 기반으로 SQL 문을 내보낸 다음, Atlas 또는 기타 외부 SQL 마이그레이션 도구를 통해 데이터베이스에 적용할 수 있습니다.

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. read your drizzle schema
    2. generated SQL representation of your schema
  ┌ 3. outputs to console
  │    
  │        
  v

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

┌───────────────────────────────────┐                  
│ (._.) now you run your migrations │           
└─┬─────────────────────────────────┘  
  │
 via Atlas
  │                                    ┌──────────────┐
  │  ┌────────────────────┐            │              │
  └──│ Atlas              ├───────────>│  Database    │      
     └────────────────────┘            │              │       
                                       └──────────────┘

[✓] done!