💡 기본 생성

📋 목차

• ⚙️ 1. Drizzle Config 설정 (옵션 상세)
• 🛠️ 2. 핵심 명령어 상세 가이드
  • generate (커밋 만들기)
  • migrate (커밋 반영하기)
  • custom (수동 SQL 작성)
• 🚨 3. 문제 해결 (Troubleshooting)
  • 상황 1: Drift (표류) 🌊
  • 상황 2: 충돌 (Conflicts) ⚔️
• 🚀 4. 배포 전략 (Production Deployment)
  • 안전한 배포 치트시트 CheckList ✅
• 🔗 레퍼런스

DB 스키마를 안전하게 변경하고 전파하는 "실무 워크플로우" 입니다. 단순히 push하는 것을 넘어, 팀 단위 협업과 배포 시나리오를 다룹니다.

⚙️ 1. Drizzle Config 설정 (옵션 상세)

drizzle.config.ts 파일은 마이그레이션 도구의 관제탑입니다.

import { defineConfig } from 'drizzle-kit';
 
export default defineConfig({
  dialect: 'postgresql', // 'mysql' | 'sqlite'
  schema: './src/db/schema', // 스키마 파일 위치 (글로브 패턴 가능 'src/**/*.schema.ts')
  out: './drizzle', // 마이그레이션 파일(.sql) 생성 위치
 
  // DB 연결 정보 (마이그레이션 실행용)
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
 
  // ⭐️ 중요 옵션들
  verbose: true,     // 터미널에 실행되는 SQL 출력
  strict: true,      // 데이터 손실 경고 무시 불가 (안전장치)
  tablesFilter: ['!private_*'], // 특정 테이블 무시 (예: Supabase 내부 테이블)
});

🛠️ 2. 핵심 명령어 상세 가이드

generate (커밋 만들기)

스키마 변경 사항을 감지해서 .sql 파일을 만듭니다. 가장 많이 씁니다.

 
npx drizzle-kit generate
 
# ⭐️ 식별하기 쉽게 이름 붙이기 (추천)
npx drizzle-kit generate --name add_user_phone
# -> drizzle/0001_add_user_phone.sql 생성됨

migrate (커밋 반영하기)

생성된 .sql 파일들을 실제 DB에 실행합니다.

npx drizzle-kit migrate

custom (수동 SQL 작성)

Drizzle ORM 스키마로 표현 못하는 것들(Trigger, Stored Procedure 등)을 만들 때 사용합니다.

# 빈 마이그레이션 파일 생성
npx drizzle-kit generate --custom --name create_audit_trigger

생성된 빈 xxxx_create_audit_trigger.sql 파일에 직접 SQL을 작성하면, 나중에 migrate 할 때 같이 실행됩니다.

🚨 3. 문제 해결 (Troubleshooting)

상황 1: Drift (표류) 🌊

"누가 몰래 DB를 수정했어요!"
Drizzle 스키마와 실제 DB 상태가 안 맞을 때 발생합니다. (예: 누군가 Supabase 대시보드에서 직접 컬럼 추가함)

1. 진단:

   npx drizzle-kit check
   # -> 차이점을 리포트로 보여줍니다.

2. 해결 A (코드 기준 동기화):
   다시 push 하거나 generate해서 DB를 내 코드에 맞춥니다. (DB 변경사항 덮어씀)
3. 해결 B (DB 기준 동기화):
   introspect (또는 pull) 명령어로 DB 상태를 스키마 파일로 역생성합니다.

   npx drizzle-kit pull

상황 2: 충돌 (Conflicts) ⚔️

동료 A와 B가 동시에 마이그레이션 파일을 만들어서 커밋했습니다.

• 0005_add_post.sql (A)
• 0005_add_comment.sql (B)
  순서 번호가 겹쳤네요!

해결:

1. 파일 이름의 숫자를 수정하거나 (수동)
2. 가장 최신 스냅샷을 삭제하고 다시 generate 합니다.
3. Drizzle Kit이 알아서 순서를 재조정하기도 합니다. (버전업되면서 똑똑해짐)

🚀 4. 배포 전략 (Production Deployment)

안전한 배포 치트시트 CheckList ✅

1. Schema Sync: 로컬에서 drizzle-kit generate 완료 후 커밋.
2. Dry Run: 실제 배포 전 테스트 DB에 먼저 적용해봄.
3. Backup: (운영 환경) 배포 직전 스냅샷/백업 필수.
4. Auto Migrate: 서버 시작 시 스크립트로 자동 실행.

NestJS 등 서버 코드에서 자동 실행하기:

// src/db/migrate.ts
import { migrate } from 'drizzle-orm/postgres-js/migrator';
import { db } from './index';
 
async function main() {
  console.log('Migrating...');
  // 'drizzle' 폴더의 sql 파일들을 읽어서 실행
  await migrate(db, { migrationsFolder: './drizzle' });
  console.log('Done!');
}
main();

주의: 서버 인스턴스가 여러 개(PM2 클러스터, K8s 파드 등)일 때, 동시에 migrate가 실행되면 락(Lock) 걸리거나 꼬일 수 있습니다. 배포 파이프라인(CI/CD)의 별도 단계 로 빼는 것이 가장 안전합니다.

📝 마무리 퀴즈

Q1. drizzle-kit generate와 drizzle-kit migrate의 차이는 무엇인가요?

✅ 정답: generate는 스키마 변경을 SQL 파일로 만들고, migrate는 그 SQL을 실제 DB에 적용합니다.

💡 상세 해설: generate는 커밋 가능한 변경 기록을 만드는 단계입니다. migrate는 운영 DB에 영향을 주는 실행 단계라서 배포 파이프라인에서 더 조심해야 합니다.

Q2. 마이그레이션 drift가 위험한 이유는 무엇인가요?

✅ 정답: 코드의 스키마, 마이그레이션 파일, 실제 DB 상태가 서로 달라져 다음 변경이 예측 불가능해지기 때문입니다.

💡 상세 해설: 운영 DB에 직접 컬럼을 추가하거나 마이그레이션 파일을 누락하면 팀원의 로컬과 CI가 다른 DB 구조를 보게 됩니다.

Q3. 영철이의 테스트 타임: 영수네 서비스가 K8s 파드 3개로 배포됩니다. 앱 시작 시 각 파드가 migrate()를 실행하면 어떤 문제가 생길 수 있나요?

✅ 정답: 여러 인스턴스가 같은 마이그레이션을 동시에 적용해 락, 충돌, 중복 실행 문제가 생길 수 있습니다.

💡 상세 해설: 마이그레이션은 애플리케이션 서버의 일반 시작 로직과 분리하는 편이 안전합니다. CI/CD의 별도 단계에서 한 번만 실행하고, 실패하면 배포를 멈추는 구조가 운영에 맞습니다.

🐣 영철이의 퇴근 일기

오늘은 마이그레이션을 DB 변경 버튼이 아니라 배포 계약으로 봐야 한다는 걸 배웠다. generate와 migrate가 분리된 이유도 이제 이해된다.

영수 님이 "게시판 점검 없이 컬럼 하나 추가할 수 있죠?"라고 물었을 때 예전 같으면 바로 가능하다고 했을 것 같다. 이제는 백업, 적용 순서, 앱 버전 호환성, 파드 동시 실행까지 먼저 확인해야 한다.

💡 "마이그레이션은 스키마 변경 파일이 아니라 운영 DB에 대한 약속이다."

내일 배포 PR을 보면 SQL 내용만 보지 말고, 롤백 가능성, drift 여부, CI에서 한 번만 실행되는지까지 체크해야겠다.

🔗 레퍼런스

• Drizzle Kit Config
• Command References

다음 장: 05. CRUD 조작 (CRUD Operations)