Ch5. 마이그레이션 파이프라인
개발부터 프로덕션까지 Prisma 마이그레이션 자동화/승인/검증 워크플로우
핵심 요약
- 설계 → 개발 환경 생성 → 정적 검증 → staging 리허설 → 프로덕션 승인 배포의 5단계 표준 워크플로우를 따릅니다.
- 정적 검증 단계에서
DROP·ALTER TYPE·대규모 UPDATE 같은 위험 키워드를 자동으로 잡아내고 통과 여부를 가립니다. - Prisma 7 CI는
--from-config-datasource·--to-schema를 사용하며 diff 종료 코드 0(동일)·2(차이)·1(오류)를 구분합니다. - 앱 배포 파이프라인과 마이그레이션 파이프라인을 분리해 실패 영향 반경과 책임 경계를 명확히 합니다.
- 핵심 테이블 변경은 한 번에 1건씩, 트래픽 저점에 배포하고 30~60분 집중 관찰하며, 표준 필드를 갖춘 운영 로그를 감사·회고용으로 남깁니다.
배포 전 이력 상태의 종료 코드
migrate status는 pending migration이 있어도 실패 종료할 수 있습니다. 배포 전에는 승인된 pending 이력과
실제 오류를 구분해 판정하고, 적용 뒤 이력이 모두 반영됐는지 확인합니다. 이력 검사가 성공했다고 DB drift가 없다는 뜻은 아닙니다.
표준 워크플로우
변경 목적, 영향 테이블, 예상 락 범위를 ADR 또는 변경 요청서에 기록합니다.
prisma migrate dev로 초안을 만든 뒤 SQL을 리뷰하기 좋은 형태로 커밋합니다.
위험 키워드(DROP, ALTER TYPE, 대규모 UPDATE) 자동 탐지 규칙을 통과해야 합니다.
실데이터 크기와 유사한 조건에서 실행 시간, 락, 실패율을 측정합니다.
승인된 창구에서 prisma migrate deploy 실행 후 지표를 모니터링합니다.
CI 체크 예시
먼저 prisma.config.ts가 직접 연결 DIRECT_DATABASE_URL을 읽고, CI의 Prisma 7.10.1이 lockfile대로 설치됐는지 확인합니다.
# CI의 비밀 저장소에서 DIRECT_DATABASE_URL을 주입한다.
pnpm exec prisma --version
pnpm exec prisma validate
pnpm exec prisma migrate status
# 읽기 전용 차이 계산: v6의 --from-url·--to-schema-datamodel은 사용하지 않는다.
pnpm exec prisma migrate diff \
--from-config-datasource \
--to-schema prisma/schema.prisma \
--exit-code| 종료 코드 | 의미 | 파이프라인 판단 |
|---|---|---|
| 0 | 구조 차이 없음 | 현재 상태와 목표 일치 |
| 2 | 구조 차이 있음 | 승인된 pending migration이 설명하는 차이인지 검토 |
| 1 | 도구·연결·입력 오류 | 비교 실패로 중단; 일치로 처리하지 않음 |
새 migration이 있으면 적용 전 diff 2가 정상일 수 있습니다. 무조건 실패시키거나 || true로 덮지 말고 승인된 변경과 비교합니다. migrate status는 _prisma_migrations와 파일 이력을 비교할 뿐 수동 DDL 전체를 탐지하지 않습니다. diff 역시 Prisma가 지원하는 구조만 비교하므로 trigger·view 등은 별도 점검합니다.
승인된 변경의 적용은 다음 명령으로 분리합니다. migrate deploy는 Client를 생성하지 않으므로 앱 빌드 단계에서 pnpm exec prisma generate를 따로 실행합니다.
pnpm exec prisma migrate deploy배포 직전 체크리스트
- 변경이 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"
}이 운영 로그가 감사 추적과 장애 회고의 기준 데이터가 됩니다.