배포 전에 로컬 DB 상태를 점검하는 체크리스트

배포 후에 "데이터를 저장했는데 조회가 안 된다"는 버그를 자주 본다. 대부분 로컬에서 마이그레이션을 제대로 검증하지 않아서다.

Prisma 스키마가 최신인지 확인한다

npx prisma validate

Prisma schema 파일이 유효한지 확인한다. syntax error나 타입 불일치가 있으면 즉시 나타난다.

마이그레이션 상태를 본다

npx prisma migrate status

이 명령으로:

• 로컬 DB가 몇 개 마이그레이션 뒤처져 있는지
• 실제로 실행돼야 할 마이그레이션이 무엇인지

확인할 수 있다. "Migrations behind" 메시지가 나오면 반드시 실행해야 한다.

마이그레이션을 직접 실행해본다

npx prisma migrate deploy

로컬에서 문제없이 실행되는지 테스트한다. 에러가 나면 마이그레이션 SQL을 봐야 한다.

일반적인 문제:

• NOT NULL 컬럼을 기존 데이터에 추가 (기본값 없이)
• UNIQUE 제약이 기존 중복 데이터와 충돌
• 외래키가 고아 레코드 때문에 실패

데이터베이스 권한을 확인한다

로컬에서는 모든 권한이 있지만, 운영 환경의 DB 사용자는 제한된 권한을 가질 수 있다.

# 환경 변수로 운영 DB를 가리킨 후
export DATABASE_URL="postgresql://user:pass@prod-db:5432/production"
npx prisma migrate deploy --skip-generate

이 명령으로 운영 DB의 실제 권한을 테스트할 수 있다.

seed 데이터가 필요한지 확인한다

Prisma seed를 사용한다면 마이그레이션 후 seed도 실행해야 한다.

npx prisma db seed

dev 환경용 초기 데이터(테스트 사용자, 카테고리 등)가 누락되면 애플리케이션이 제대로 작동하지 않을 수 있다.

배포 전에 변경사항 한 번 더 리뷰한다

Prisma schema 변경 사항을 다시 본다:

1. 새로 추가한 컬럼이 정말 필요한가
2. 기본값이나 제약이 제대로 정의되어 있는가
3. 타입이 애플리케이션 코드와 일치하는가

스키마는 한 번 배포되면 롤백이 어렵다. 신중해야 한다.

운영 환경 마이그레이션은 여유 시간을 두고 실행한다

실제 배포 전에 운영 환경에서 마이그레이션을 미리 실행할 수 있다면 좋다. 문제가 생기면 대응할 시간이 있다.

또한 롤백 계획을 미리 준비한다. 마이그레이션이 실패했을 때 어떻게 복구할 건지 알아야 한다.