Prisma 마이그레이션이 꼬일 때 확인할 순서

운영 중 DB 마이그레이션이 막히면 당황하기 쉽다. 하지만 문제를 크게 잡지 말고 작은 신호부터 체계적으로 확인하면 대부분 5분 안에 원인을 찾을 수 있다.

먼저 마이그레이션 상태 확인하기

Prisma는 마이그레이션 히스토리를 DB에 기록한다. 현재 상태를 정확히 파악하는 게 모든 디버깅의 시작이다.

npx prisma migrate status
npx prisma validate

이 명령어들이 보여주는 출력을 읽는 게 중요하다. pending migrations 항목이 있다면, 아직 적용되지 않은 마이그레이션이 있다는 뜻이다.

스키마와 마이그레이션 파일 맞춰보기

prisma.schema가 실제 DB 상태와 얼마나 일치하는지 확인해야 한다. 스키마를 고쳤는데 마이그레이션을 만들지 않았거나, 마이그레이션만 있고 스키마는 반영하지 않은 경우가 많다.

• 스키마 파일 (schema.prisma)을 열어서 최근 변경사항을 읽는다
• prisma/migrations/ 폴더의 가장 최근 마이그레이션 파일을 확인한다
• 둘이 일치하지 않으면, 먼저 스키마를 정리해야 한다

백업 확인 후 작은 실험하기

로컬 환경이 있다면 로컬에서 먼저 마이그레이션을 시도해본다. 로컬과 운영 환경의 차이를 확인할 수 있기 때문이다.

npx prisma migrate dev --name test_migration

로컬에서 성공하면, 운영 환경의 뭔가 다른 부분을 찾는 데 집중한다. 환경변수, DB 연결 권한, 또는 이전 마이그레이션의 상태 같은 것들이다.

실패했을 때 로그와 응답 읽기

에러 메시지를 자세히 읽으면 대부분 다음 단계가 명확하다. "column already exists", "foreign key constraint", "type mismatch" 같은 구체적인 정보를 찾자.

• 같은 이름의 칼럼이 이미 있진 않은가?
• 참조하려는 테이블이 존재하는가?
• 데이터 타입이 호환되는가?

마이그레이션 롤백이 필요할 때

긴급 상황이면 마지막 마이그레이션을 롤백할 수 있다.

npx prisma migrate resolve --rolled-back <migration-name>

이 방식으로 "이 마이그레이션은 이미 실패했고 되돌렸다"고 Prisma에 알린다. 그 다음 마이그레이션 파일을 정정해서 다시 시도할 수 있다.

마지막 확인: 실제 데이터

마이그레이션이 성공했다고 해서 끝이 아니다. 실제 화면에서 데이터가 정상으로 조회되는지 확인한다. 쿼리 결과가 예상과 다르면 스키마 정의를 다시 확인해야 한다.