Ch5. 마이그레이션 파이프라인
개발부터 프로덕션까지 Prisma 마이그레이션 자동화/승인/검증 워크플로우
표준 워크플로우
변경 목적, 영향 테이블, 예상 락 범위를 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"
}운영 로그는 감사 추적과 장애 회고의 기준 데이터입니다.