Ch6. 마이그레이션 실패 대응
실패 유형 분류, 즉시 대응, Prisma migrate resolve 기반 복구 절차
실패는 전제하고 설계한다
프로덕션 마이그레이션은 실패 가능성을 기본값으로 둬야 합니다. 핵심은 빠른 원인 분류와 서비스 영향 최소화입니다.
실패 유형 분류
| 유형 | 징후 | 우선 대응 |
|---|---|---|
| 사전 실패 (Pre-apply) | SQL 검증/권한 체크 단계에서 실패 | 배포 중단, 원인 수정 후 재시도 |
| 부분 적용 (Partial apply) | 일부 DDL 반영 후 중단 | 현재 DB 상태 캡처, 수동 정합성 점검 |
| 장기 락/타임아웃 | 트랜잭션 대기 증가, API 지연 | 즉시 중단 여부 결정, 트래픽 제어 |
| 애플리케이션 비호환 | 배포 직후 5xx 급증 | 코드 롤백 또는 feature flag 다운 |
즉시 대응 플로우
점검 커맨드 예시
# 마이그레이션 기록/상태 확인
npx prisma migrate status
# 상태 정리(정상/실패 마킹)
npx prisma migrate resolve --applied "202602070930_add_invoice_snapshot"
npx prisma migrate resolve --rolled-back "202602070930_add_invoice_snapshot"migrate resolve는 히스토리 메타데이터를 조정하는 작업입니다.
실제 스키마 상태 확인 없이 실행하면 추가 장애를 유발할 수 있으므로, DBA 검토를 선행합니다.
장애 중 커뮤니케이션 템플릿
[DB-MIGRATION-INCIDENT]
- 서비스: billing-api
- 환경: prod
- 시작 시각: 2026-02-07 09:32 KST
- 영향: 결제 API 지연(약 18%)
- 현재 상태: 코드 롤백 완료, DB 정합성 점검 중
- 다음 업데이트 ETA: 10분재시도 기준
- 동일 SQL을 그대로 재실행하지 않습니다.
- 실패 원인을 재현 가능한 형태로 기록합니다.
- 실패 시점 이전/이후 DB 객체 상태를 비교합니다.
- 재시도 전 관측 대시보드와 알림 임계치를 임시 강화합니다.
회고 필수 항목
- 왜 실패를 사전에 탐지하지 못했는가
- 승인/검증 단계의 누락 항목은 무엇인가
- 자동화할 수 있는 사전 체크는 무엇인가
- 다음 릴리스에서 제거할 운영 리스크는 무엇인가