Ch5. 마이그레이션 파이프라인
개발부터 프로덕션까지 Prisma 마이그레이션 자동화/승인/검증 워크플로우
핵심 요약
- 설계 → 개발 환경 생성 → 정적 검증 → staging 리허설 → 프로덕션 승인 배포의 5단계 표준 워크플로우를 따릅니다.
- 정적 검증 단계에서
DROP·ALTER TYPE·대규모 UPDATE 같은 위험 키워드를 자동으로 잡아내고 통과 여부를 가립니다. - CI에서
migrate diff --from-url $PROD --to-schema-datamodel ... --exit-code로 운영 스키마와의 차이를 점검합니다. - 앱 배포 파이프라인과 마이그레이션 파이프라인을 분리해 실패 영향 반경과 책임 경계를 명확히 합니다.
- 핵심 테이블 변경은 한 번에 1건씩, 트래픽 저점에 배포하고 30~60분 집중 관찰하며, 표준 필드를 갖춘 운영 로그를 감사·회고용으로 남깁니다.
표준 워크플로우
변경 목적, 영향 테이블, 예상 락 범위를 ADR 또는 변경 요청서에 기록합니다.
prisma migrate dev로 초안을 만든 뒤 SQL을 리뷰하기 좋은 형태로 커밋합니다.
위험 키워드(DROP, ALTER TYPE, 대규모 UPDATE) 자동 탐지 규칙을 통과해야 합니다.
실데이터 크기와 유사한 조건에서 실행 시간, 락, 실패율을 측정합니다.
승인된 창구에서 prisma migrate deploy 실행 후 지표를 모니터링합니다.
CI 체크 예시
# 마이그레이션 상태 확인
npx prisma migrate status
# 스키마 차이 점검 (예: staged schema vs production)
npx prisma migrate diff \
--from-url "$PROD_DATABASE_URL" \
--to-schema-datamodel prisma/schema.prisma \
--exit-code배포 직전 체크리스트
- 변경이 Expand/Contract 어느 단계인지 명확함
- 백필 스크립트 실행 시간과 중단 기준 정의 완료
- 실패 시 복구 절차(롤포워드/롤백) 문서화 완료
- DBA 또는 운영 승인자 사인오프 완료
- 관측 대시보드/알림 채널이 준비됨
배포 윈도우 운영
| 항목 | 권장 기준 |
|---|---|
| 실행 시간대 | 트래픽 저점 |
| 변경 동시성 | 핵심 테이블 변경은 1건씩 |
| 모니터링 최소 시간 | 배포 후 30~60분 집중 관찰 |
| 커뮤니케이션 | 변경 시작/종료/이상 징후를 채널에 고정 포맷으로 공지 |
배포 자동화 분리
- 앱 배포 파이프라인: 이미지 배포, 헬스체크, 트래픽 전환
- 마이그레이션 파이프라인: 승인 기반 실행, 점검, 결과 기록
두 파이프라인을 나눠 두면 실패가 번지는 범위가 줄고 책임 경계도 분명해집니다.
운영 로그 표준 필드
{
"event": "prisma_migration_deploy",
"service": "billing-api",
"environment": "prod",
"migration_id": "202602070930_add_invoice_snapshot",
"status": "success",
"duration_ms": 18422,
"operator": "ci-bot"
}이 운영 로그가 감사 추적과 장애 회고의 기준 데이터가 됩니다.