Ch4. 마이그레이션 전략
Expand/Contract 기반 무중단 마이그레이션과 위험 변경 분리 전략
핵심 요약
- 스키마 변경과 앱 배포를 한 릴리스에 묶지 않고,
DROP·RENAME같은 파괴적 변경은 별도 릴리스로 분리합니다. - Expand(컬럼·인덱스 추가) → Transition(백필·Dual Write·검증) → Contract(구 컬럼·fallback 제거) 단계로 무중단 마이그레이션을 진행합니다.
- 프로덕션에서는
migrate dev를 쓰지 않고migrate deploy만 허용하고,migrate status·migrate diff로 드리프트를 점검합니다. - 컬럼 타입 축소·이름 변경·NOT NULL 추가는 신규 컬럼·백필·검증을 거쳐 점진 전환합니다.
- 2026-03 발표된 Prisma Next(Prisma 8)는 graph-based 마이그레이션을 예고했고 Postgres GA는 2026년 6~7월 예정이며, Prisma 7은 12개월 지원이 보장됩니다.
기본 원칙
- 스키마 변경과 애플리케이션 배포를 한 번에 묶지 않습니다.
- 파괴적 변경(
DROP,RENAME)은 별도 릴리스로 분리합니다. - 모든 변경은 되돌릴 수 있는 단계로 쪼갭니다.
Expand/Contract 패턴
Expand 단계
- nullable 컬럼 추가
- 새 인덱스 생성
- 기존 로직과 호환되는 기본값/트리거 준비
Transition 단계
- 백필 배치 수행
- 애플리케이션 Dual Write/Read fallback 적용
- 데이터 정합성 검증
Contract 단계
- 구 컬럼/인덱스 제거
- fallback 코드 제거
- 운영 지표 안정 확인
Prisma Migrate 운용 규칙
- 로컬:
prisma migrate dev - 배포:
prisma migrate deploy - 드리프트 점검:
prisma migrate status,prisma migrate diff
migrate dev는 개발 워크플로우에서만 씁니다.
프로덕션에서는 migrate deploy 외에는 쓰지 않도록 정책으로 못 박습니다.
위험 변경 분리 규칙
| 변경 유형 | 처리 방법 |
|---|---|
| 컬럼 타입 축소 | 새 컬럼 추가 후 점진 전환 |
| 컬럼 이름 변경 | 새 컬럼 추가 + 백필 + 코드 전환 후 제거 |
| 대용량 인덱스 생성 | 트래픽 저점 배치, 가능하면 online 옵션 활용 |
| NOT NULL 추가 | 사전 백필 + 검증 후 제약 적용 |
배포 단위 설계 예시
Release A: 새 컬럼 추가 + 앱에서 dual write 시작
Release B: 백필 완료 + read 경로 전환
Release C: 구 컬럼 제거 + 코드 정리Prisma Next: Graph-Based Migrations 전망
2026-03-04 Prisma 블로그가 Prisma Next(→ Prisma 8)를 발표하면서 선형 마이그레이션 파일 대신 Git-like 브랜치 모델의 graph-based migrations을 예고했습니다. 지금 쓰는 Prisma 7의 선형 마이그레이션은 앞으로 12개월간 지원됩니다.
Prisma Next 공식 로드맵 (2026-03-20 갱신)
| 시기 | 마일스톤 | 비고 |
|---|---|---|
| 2026년 4월 | 외부 기여 오픈 + 안정 확장 API | 커뮤니티 참여 시작 |
| 2026년 5월 | Early Access (Postgres + SQLite) | 첫 공개 프리뷰 |
| 2026년 6~7월 | Postgres GA | 프로덕션 사용 가능 |
Prisma Next는 Prisma 7과 호환 레이어를 제공해 둘을 나란히 돌릴 수 있도록 설계 중입니다. 그래서 Prisma 7 → Next 전환은 빅뱅 마이그레이션이 아니라 점진적으로 넘어갈 수 있습니다.
이 핸드북의 Expand/Contract 패턴과 migrate deploy 기반 워크플로우는 Prisma 7을 전제로 하므로,
Prisma Next GA 이후에는 마이그레이션 파이프라인 구조를 다시 설계해야 합니다.
금지 안티패턴
- 단일 릴리스에서
ALTER TABLE ... DROP COLUMN+ 앱 코드 동시 반영 - 트래픽 피크 시간에 대용량 백필 실행
- 마이그레이션 SQL을 코드 리뷰 없이 즉시 배포
- 복구 계획 없이 파괴적 변경 수행