💡 기본 생성

📋 목차

• ⚙️ 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)의 별도 단계 로 빼는 것이 가장 안전합니다.

🔗 레퍼런스

• Drizzle Kit Config
• Command References

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