# DB 스키마 변경 워크플로우

> **목적** 마이그레이션 충돌 방지 및 프로덕션 반영 사고 예방
> **대상** 온보더즈 개발팀 전원
> **도구** Drizzle ORM + Drizzle Kit

---

## 1. 핵심 원칙

1. **마이그레이션 파일은 손으로 수정하지 않는다** — 자동 생성된 파일만 커밋
2. **동시에 스키마를 건드리는 작업은 한 명만** — 착수 전 팀에 공유

---

## 2. 환경별 DB 구성

| 환경 | 용도 | 데이터 | 반영 방법 |
|---|---|---|---|
| **local** | 개인 개발 | 개인 더미 | `drizzle-kit push` (자유롭게) |
| **development** | 통합 테스트 | 소량 더미 | 배포 Pre-deploy Step으로 자동 실행 |
| **staging** | 프로덕션 검증 | 소량 더미 | 배포 Pre-deploy Step으로 자동 실행 |
| **production** | 서비스 운영 | 실데이터 | 배포 Pre-deploy Step으로 자동 실행 |

> ⚠️ `drizzle-kit push`는 local 전용. 
> development/staging/production에서는 절대 사용 금지.

---

## 3. 스키마 변경 플로우

```
스키마 변경 착수 전
  └─ 슬랙에 "DB 스키마 작업 시작합니다" 공유
       └─ 다른 팀원 동시 작업 여부 확인

브랜치 생성 → 스키마 수정 → 마이그레이션 생성
  └─ drizzle-kit generate

PR 생성
  └─ PR 본문에 변경된 테이블/컬럼 명시 (아래 템플릿 참고)
  └─ 팀원 리뷰 필수 (최소 1명 approve)

develop 머지 → development DB 자동 반영 확인

staging 머지 → staging DB 자동 반영
  └─ 마스킹된 프로덕션 데이터로 주요 기능 검증
  └─ 이상 없으면 프로덕션 배포 진행

프로덕션 배포
  └─ Railway Pre-deploy Step에서 migrate 자동 실행
  └─ migrate 성공 시 코드 배포 진행 / 실패 시 배포 중단
```

---

## 4. 마이그레이션 생성 규칙

```bash
# 스키마 파일 수정 후
npx drizzle-kit generate

# 생성된 파일 반드시 확인
# 예상한 변경만 들어있는지 diff 검토 후 커밋
git add drizzle/migrations/
git commit -m "db: add users.phone column"
```

**커밋 컨벤션**

```
db: <변경 내용 한 줄 요약>

예시)
db: add users.phone column
db: rename orders.status → orders.state
db: drop deprecated sessions table
```

---

## 5. 마이그레이션 충돌 해결

팀원 간 마이그레이션이 겹치면 타임스탬프 순서가 꼬일 수 있음.

### 충돌 시 절차

1. **작업 중단 — 직접 수정하지 않는다**
2. 슬랙에 상황 공유
3. 두 브랜치 중 **나중에 생성된 쪽**이 리베이스
4. 리베이스 후 마이그레이션 재생성

```bash
# 나중 브랜치에서
git rebase dev

# 스키마 충돌 해결 후 기존 마이그레이션 파일 삭제 후 재생성
npx drizzle-kit generate
```

> 마이그레이션 파일을 손으로 합치지 말 것. 반드시 재생성.

---

## 6. 프로덕션 반영 절차

> Railway 기준. staging 검증 → 프로덕션 Pre-deploy migrate → 코드 배포 순서.

### Step 1 — development 확인

PR 머지 후 development DB에 자동 반영된 결과를 최소 하루 확인.

### Step 2 — staging 검증

stating 머지 시 staging에 자동 마이그레이션 실행.

- staging DB는 프로덕션과 동일한 스키마 + 개발환경 데이터로 구성
- 변경된 테이블/컬럼과 관련된 주요 기능 직접 테스트
- 슬랙에 staging 검증 완료 공유 후 프로덕션 배포 진행

### Step 3 — 프로덕션 배포 (migrate 자동 실행)

Railway  설정으로 배포 전 migrate 자동 실행.

```
# Railway 대시보드 → Service → Settings → Deploy → Pre-deploy Command
npx drizzle-kit migrate
```

- migrate 성공 → 코드 배포 자동 진행
- migrate 실패 → 배포 자동 중단 (코드는 변경되지 않음)

### Step 4 — 배포 후 smoke test

- 변경된 기능 직접 확인
- 이상 없으면 슬랙에 완료 공유

### 프로덕션 반영 금지 시간대

| 금지 시간대 | 사유 |
|---|---|
| 월~금 16:00–18:00 | 퇴근 시간 |
| 금요일 17:00 이후 | 주말 대응 불가 |
| 클라이언트 데모 당일 | 리스크 회피 |

### staging DB 데이터 관리

프로덕션 데이터를 staging에 주기적으로 동기화. 개인정보는 반드시 마스킹 후 복사.

```sql
-- 마스킹 예시 (users 테이블)
UPDATE users SET
  email = CONCAT('user_', id, '@example.com'),
  phone = '010-0000-0000',
  name  = CONCAT('테스트유저', id);
```

> 동기화 주기는 팀 상황에 맞게 결정. 최소 월 1회 권장.

---

## 7. PR 스키마 변경 체크리스트

PR에 스키마 변경이 포함된 경우 아래 항목을 PR 본문에 포함.

```markdown
## DB 변경 사항
- [ ] 변경된 테이블: `테이블명`
- [ ] 변경 종류: 컬럼 추가 / 수정 / 삭제 / 인덱스 / 제약조건
- [ ] 데이터 마이그레이션 필요 여부: Y / N
- [ ] development 반영 확인: Y / N
```

---

## 8. 자주 하는 실수 & 금지 행동

| 행동 | 이유 |
|---|---|
| `drizzle-kit push`를 개발/운영에서 사용 | 마이그레이션 히스토리가 남지 않음 |
| 마이그레이션 파일 직접 수정 | 체크섬 불일치로 이후 마이그레이션 실패 |
| 스키마 변경을 팀에 알리지 않고 착수 | 충돌 원인 |
| 금요일 오후 프로덕션 반영 | 주말 장애 대응 불가 |

---

*최초 작성: 2026.03 | 다음 리뷰: 분기별*

마이그레이션 충돌 방지 및 프로덕션 반영 사고 예방

DB 스키마 변경 워크플로우

코드 리뷰