Drizzle 마이그레이션 기초

SQL 데이터베이스는 저장할 엔티티의 엄격한 스키마를 사전에 지정해야 하며, 이러한 엔티티의 형태를 변경해야 할 때는 스키마 마이그레이션을 통해 수행해야 합니다.

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

데이터베이스 우선은 데이터베이스 스키마가 신뢰할 수 있는 소스인 경우입니다. 데이터베이스에서 직접 또는 데이터베이스 마이그레이션 도구를 통해 데이터베이스 스키마를 관리한 다음, 데이터베이스 스키마를 코드베이스 애플리케이션 수준 엔티티로 가져옵니다.

코드베이스 우선은 코드베이스의 데이터베이스 스키마가 신뢰할 수 있는 소스이며 버전 관리 하에 있는 경우입니다. 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!