Prisma 마이그레이션 문제 디버깅하는 법

Prisma 마이그레이션은 로컬 개발 환경과 운영 서버에서 다르게 동작할 가능성이 높다. 데이터 타입, DATABASE_URL, 마이그레이션 상태가 각각 다를 수 있기 때문이다. 혼자 개발할수록 각 단계에서 확인한 값과 변경한 값을 따로 기록하는 습관이 중요하다.

먼저 스키마 검증하기

Prisma의 스키마 정의가 올바른지 먼저 확인한다. 타입 불일치나 필드 누락으로 인한 마이그레이션 실패를 조기에 발견할 수 있다.

npx prisma validate
npx prisma migrate status

마이그레이션 이력 확인

로컬과 운영에서 적용된 마이그레이션이 같은지 확인한다. 서버에만 남겨진 미실행 마이그레이션이 있으면 롤백이 필요할 수 있다.

npx prisma migrate resolve --rolled-back <migration_name>

정상 상태 확립

문제를 해결했다고 생각하더라도 로컬과 운영에서 동일한 결과가 나오는지 검증한다. 데이터 타입, 제약 조건, 기본값 모두를 확인해야 한다.

• 확인할 값: 스키마 정의, 마이그레이션 상태, 실제 DB 구조
• 비교 기준: 이전 성공한 마이그레이션과의 차이
• 기록할 것: 오류 메시지, 실행한 명령어, 변경 전후 상태

단계적 롤백과 재적용

여러 마이그레이션을 한 번에 되돌리지 말고 가장 최근 변경 하나씩 무르면서 어느 부분이 문제인지 찾는다.

npx prisma migrate resolve --rolled-back "$(npx prisma migrate status | grep 'Pending' | head -1)"
npx prisma migrate deploy

완료 기준

1. 스키마 검증이 성공하는가
2. 로컬과 운영 마이그레이션 상태가 일치하는가
3. 데이터 타입과 제약 조건이 기대한 대로인가

마이그레이션은 데이터 손상과 직결되므로 한 번에 하나씩 작은 변경을 적용하고 검증하는 방식이 가장 안전하다.