Ch6. 마이그레이션 실패 대응
실패 유형 분류, 즉시 대응, Prisma migrate resolve 기반 복구 절차
핵심 요약
- 프로덕션 마이그레이션은 실패를 기본 전제로 두고, 원인을 빠르게 분류해 서비스 영향을 최소화하는 데 집중합니다.
- 실패를 사전 실패·부분 적용·장기 락/타임아웃·앱 비호환 네 유형으로 분류해 우선 대응을 다르게 가져갑니다.
- 사용자 영향이 있으면 트래픽 완화와 코드 롤백을 먼저 하고, 그다음 DB 상태를 점검합니다.
prisma migrate resolve --applied|--rolled-back는 히스토리 메타데이터만 조정하므로 DBA 검토를 선행합니다.- 재시도 시 동일 SQL을 그대로 재실행하지 않고, 실패 원인을 재현 가능하게 기록한 뒤 알림 임계치를 임시 강화합니다.
실패는 전제하고 설계한다
프로덕션 마이그레이션은 실패할 수 있다는 전제로 설계해야 합니다. 원인을 빠르게 분류하고 서비스 영향을 최소화하는 것이 관건입니다.
실패 유형 분류
| 유형 | 징후 | 우선 대응 |
|---|---|---|
| 사전 실패 (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 객체 상태를 비교합니다.
- 재시도 전 관측 대시보드와 알림 임계치를 임시 강화합니다.
회고 필수 항목
- 왜 실패를 사전에 탐지하지 못했는가
- 승인/검증 단계의 누락 항목은 무엇인가
- 자동화할 수 있는 사전 체크는 무엇인가
- 다음 릴리스에서 제거할 운영 리스크는 무엇인가