데이터베이스 마이그레이션이 실패하지 않도록 미리 확인할 것

화면만 보고 판단하지 않는다

Postgres나 MySQL 같은 데이터베이스 문제가 생기면, 웹 화면에서는 막연한 에러만 보인다. 실제로 어떤 쿼리가 실패했는지, 스키마가 제대로 반영되었는지, 마이그레이션이 완료되었는지는 로그와 명령어로만 확인할 수 있다.

데이터 계층 문제의 핵심은 단편적인 에러 메시지가 아니라, 마이그레이션 상태와 스키마 일관성을 확인하는 것이다. 로컬과 운영 환경의 DATABASE_URL도 다를 수 있으니, 각 단계에서 어디서 차이가 나는지 확인해야 한다.

먼저 데이터베이스 연결을 확인한다

데이터베이스 문제를 해결하려면, 가장 먼저 연결이 제대로 되는지 확인해야 한다:

• 먼저 볼 값: DATABASE_URL이 올바른가, 마이그레이션 상태는 어떤가
• 함께 비교할 값: 정상 상태에서의 마이그레이션 히스토리
• 남겨둘 기록: Prisma 스키마, 마이그레이션 로그, SQL 쿼리

마이그레이션 상태를 점검한다

Prisma로 데이터베이스 스키마를 관리할 때, 마이그레이션이 제대로 적용되었는지 확인하는 것이 중요하다. 로컬 개발 환경과 운영 환경의 마이그레이션 상태가 다를 수 있기 때문이다:

npx prisma validate
npx prisma migrate status

이 명령들로 현재 스키마의 유효성과 마이그레이션 상태를 확인할 수 있다.

Prisma 스키마를 검증한다

Prisma schema.prisma 파일의 문법이 올바른지, 데이터베이스의 실제 스키마와 일치하는지 확인한다. 스키마와 데이터베이스가 불일치하면 쿼리가 실패한다.

마이그레이션 순서를 의심한다

여러 마이그레이션을 한 번에 적용할 때, 순서 때문에 에러가 발생할 수 있다. 마이그레이션 히스토리를 보고, 어떤 순서로 실행되었는지, 실패한 마이그레이션이 있는지 확인한다.

백업이 있는지 확인한다

데이터베이스 작업을 하기 전에, 현재 데이터의 백업이 있는지 반드시 확인해야 한다. 마이그레이션 실패로 데이터가 손상되었을 때 원상복구할 수 있기 때문이다.

단계별로 검증한다

같은 문제가 반복되는 것을 방지하려면 확인 순서를 고정한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 마이그레이션 상태와 스키마 일치를 명확히 설명할 수 있는지 확인한다
3. 데이터베이스 연결, 쿼리 실행, 백업 상태를 최종 확인한다

다음을 위해 기록한다

데이터베이스 문제를 해결한 후, 어떤 마이그레이션이 문제였는지, 어떻게 수정했는지 정리해두면, 비슷한 문제가 생겼을 때 빠르게 대응할 수 있다.