Prisma 마이그레이션이 실패했을 때 대응

Prisma migration이 실패하면 데이터베이스 상태가 중간에 걸린다. 당황하지 말고 상태를 먼저 파악해야 한다.

마이그레이션 상태 확인

먼저 현재 상태를 본다:

npx prisma migrate status
# Drift detected: ...pending migrations...

마이그레이션 히스토리 폴더를 본다:

ls -la prisma/migrations/
# 각 마이그레이션 폴더와 migration.sql 파일

어디까지 적용되었고, 어디서 실패했는지 파악한다.

마이그레이션 로그 보기

데이터베이스에 기록된 마이그레이션 로그를 본다:

# PostgreSQL
SELECT * FROM "_prisma_migrations" ORDER BY "startedAt" DESC;

# SQLite
SELECT * FROM "_prisma_migrations" ORDER BY "startedAt" DESC;

마지막 항목의 logs 칼럼을 보면 에러 메시지가 있을 수 있다.

실패 원인 파악

일반적인 원인들:

문법 에러: migration.sql의 SQL이 잘못되었다. 파일을 열어서 직접 확인한다.

외래키 제약: 이미 존재하는 데이터와 충돌한다.

중복 컬럼: 이미 있는 컬럼을 다시 추가하려고 했다.

권한 문제: 데이터베이스 사용자 권한이 부족하다.

각각 다른 해결 방법이 필요하다.

마이그레이션 롤백

실패한 마이그레이션을 되돌리려면:

# 마이그레이션 전까지의 상태로 롤백
npx prisma migrate resolve --rolled-back <migration-name>

# 또는 특정 마이그레이션을 실패한 것으로 표시
npx prisma migrate resolve --failed <migration-name>

그러면 다음번에 다시 실행할 수 있다.

스키마 vs 데이터베이스 동기화

만약 데이터베이스가 망가져서 Prisma 스키마와 맞지 않는다면:

# 현재 데이터베이스 스키마를 Prisma 스키마로 당기기
npx prisma db pull

# prisma/schema.prisma가 업데이트된다

그러면 실제 데이터베이스 상태를 정확히 알 수 있다.

개발 환경에서의 리셋

개발 환경이라면 데이터 손실이 문제 아니다. 완전히 리셋할 수 있다:

# 데이터베이스 초기화 (조심!)
npx prisma migrate reset

# y를 입력하면:
# 1. 모든 테이블 삭제
# 2. 모든 마이그레이션 다시 실행
# 3. seed 실행 (있다면)

이 과정에서 seed.ts가 있다면 테스트 데이터도 다시 들어간다.

운영 환경 복구

운영 데이터베이스는 조심스럽다. 이 경우:

1. 백업을 먼저 받는다
2. 실패한 마이그레이션의 SQL을 수동으로 실행해본다
3. 데이터 손실이 없는지 확인한다
4. 그 후 Prisma에서 실패를 표시한다

# 백업
pg_dump dbname > backup.sql

# SQL 수동 실행 (매우 신중하게)
psql dbname < migration.sql

# 성공했으면 Prisma에 알리기
npx prisma migrate resolve --rolled-back <migration-name>

다음 마이그레이션 생성

문제를 해결한 후 새로운 마이그레이션을 생성한다:

npx prisma migrate dev --name fix_schema_issue

# 또는 스키마만 수정하고 마이그레이션 생성
npm run prisma migrate dev

예방

다음부터 이런 상황을 피하려면:

• 마이그레이션을 정기적으로 테스트한다
• 프로덕션 배포 전에 스테이징에서 마이그레이션을 실행해본다
• 마이그레이션이 복잡하면 롤백 계획을 세워둔다
• 데이터베이스 백업을 항상 준비한다