Prisma 마이그레이션 충돌 해결 가이드
운영(production) 데이터베이스에서 prisma migrate reset을 실행하지 마세요.
마이그레이션이 수정되었거나 스키마를 리셋해야 한다는 메시지가 나타나면 중단하세요. 리셋을 하면 모든 데이터가 삭제됩니다. 데이터를 잃지 않고도 이러한 충돌을 수동으로 해결할 수 있습니다.
일반적인 Prisma 오류 및 해결 방법
오류: 마이그레이션 실행 중 실패 (P3018)
• SQL 파일을 수정하세요.
• 실행: npx prisma migrate resolve --rolled-back [migration_name]
• 실행: npx prisma db execute --file [path_to_sql_file]
• 실행: npx prisma migrate resolve --applied [migration_name]
오류: 적용된 후 마이그레이션이 수정됨 (Checksum 불일치)
• 현재 마이그레이션 파일의 SHA-256 해시를 계산하세요.
• _prisma_migrations 테이블의 checksum을 업데이트하세요.
• 중요: 해당 마이그레이션 이름에 해당하는 모든 행을 업데이트하세요. rolled_back_at으로 필터링하지 마세요.
오류: Shadow 데이터베이스 컬럼 누락 (P3006) • 이는 한 마이그레이션이 이후의 마이그레이션에서 생성되는 컬럼을 참조할 때 발생합니다. • Prisma는 타임스탬프 순서대로 마이그레이션을 다시 실행합니다. • 해결 방법: 해당 컬럼이 처음 생성되는 마이그레이션으로 SQL 코드를 이동하세요.
오류: RLS 정책으로 인해 DROP COLUMN 차단됨
• PostgreSQL의 Row Level Security(RLS)는 정책을 컬럼에 결합합니다.
• 해결 방법: 컬럼을 삭제할 때 CASCADE를 사용하세요.
• 예시: ALTER TABLE "my_table" DROP COLUMN IF EXISTS "tenant_id" CASCADE;
안전한 마이그레이션을 위한 모범 사례
- 먼저 데이터베이스를 쿼리하세요. 컬럼이나 인덱스의 존재 여부를 추측하지 마세요. 마이그레이션 코드를 작성하기 전에 직접 SQL 쿼리를 사용하여 실제 데이터베이스 스키마를 확인하세요.
IF EXISTS및IF NOT EXISTS를 사용하세요. 이렇게 하면 마이그레이션이 멱등성(idempotent)을 갖게 됩니다. 멱등성이 보장된 마이그레이션은 오류 없이 여러 번 실행될 수 있습니다.- 제약 조건(constraints)에는
DO블록을 사용하세요. 외래 키(Foreign Key) 추가 시 제약 조건 이름이 이미 존재하는지 확인하는 로직으로 감싸세요. - Row Level Security를 사용하는 경우 삭제(drop) 시 항상
CASCADE를 사용하세요.
요약 표
• P3018 (실행 중 실패): SQL을 수정하고 resolve --rolled-back 및 resolve --applied를 사용하세요.
• Checksum 불일치: 새 해시를 계산하고 _prisma_migrations의 모든 행을 업데이트하세요.
• Shadow DB 오류: 타임스탬프 순서를 확인하고 SQL 로직을 이동하세요.
• RLS 오류: DROP 문에 CASCADE를 추가하세요.