Ch4. 마이그레이션 전략
Expand/Contract 기반 무중단 마이그레이션과 위험 변경 분리 전략
핵심 요약
- 스키마 변경과 앱 배포를 한 릴리스에 묶지 않고,
DROP·RENAME같은 파괴적 변경은 별도 릴리스로 분리합니다. - Expand(컬럼·인덱스 추가) → Transition(백필·Dual Write·검증) → Contract(구 컬럼·fallback 제거) 단계로 무중단 마이그레이션을 진행합니다.
- 프로덕션 적용은 프로젝트에 고정한 Prisma 7의
migrate deploy로 수행합니다.migrate status는 이력 상태,migrate diff는 실제 DB 구조와 원하는 스키마 차이를 확인합니다. - 컬럼 타입 축소·이름 변경·NOT NULL 추가는 신규 컬럼·백필·검증을 거쳐 점진 전환합니다.
- 2026-10-23 기준 Prisma 8은 RC이며 Prisma 7은 8 GA 이후 18개월 지원됩니다. 예전 6~7월 GA 예상과 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 전망
이전 Prisma Next의 월별 로드맵을 현재 출시 상태로 해석하지 않습니다. Release status는 2026-10-23에도 Prisma ORM 8을 release candidate로 표시하며, GA는 10월 예정으로만 안내합니다. 이미 10월이라는 이유로 GA를 가정하지 않습니다.
| 경로 | 운영 결정 |
|---|---|
| Prisma 7 운영 유지 | prisma·@prisma/client를 7.10.1로 고정하고 기존 Migrate 유지 |
| Prisma 8 평가 | RC 버전과 해당 RC upgrade guide를 고정하고 별도 preview DB에서 검증 |
| 7→8 병행 | 공식 orm init --from-prisma7-schema 지원 범위와 미지원 기능을 먼저 확인 |
| 지원 기간 | Prisma 7은 8 GA부터 18개월; Prisma 6 보안 패치는 2026-11-19 종료 |
8 RC에서는 $extends, 일부 nested write, transaction isolation, 기존 P2002 형태 오류 코드 등 호환성이 완성되지 않았습니다. 새 CLI와 database별 runtime package는 버전 번호도 따로 움직입니다. 운영 Migrate와 런타임을 한 번에 바꾸지 말고, 계약·오류 처리·쿼리 결과를 비교해 통과한 범위부터 전환합니다.
2026-10-02 Changelog · Release status.
금지 안티패턴
- 단일 릴리스에서
ALTER TABLE ... DROP COLUMN+ 앱 코드 동시 반영 - 트래픽 피크 시간에 대용량 백필 실행
- 마이그레이션 SQL을 코드 리뷰 없이 즉시 배포
- 복구 계획 없이 파괴적 변경 수행