DB 스키마 변경이 안 먹혔을 때 확인하는 순서

Prisma로 스키마를 변경한 후 배포했는데 반영이 안 됐다고 느껴본 적이 있다. 처음엔 마이그레이션 파일이 빌드에 포함되지 않았거나, 환경 변수가 잘못됐거나, 아니면 배포 시 마이그레이션이 스킵된 경우다.

문제는 한 가지만 보면 놓치기 쉽다. 데이터 계층 전체를 따라가며 어느 단계에서 멈췄는지 파악하는 게 핵심이다.

먼저 확인할 것: 마이그레이션 상태

npx prisma migrate status
npx prisma validate

이 두 명령으로 현재 상태를 정확히 파악한다. status는 대기 중인 마이그레이션이 있는지, validate는 schema.prisma 문법이 맞는지 본다.

마이그레이션이 "pending" 상태라면 수동으로 적용하지 않았다는 뜻이다. 배포 환경에서 자동으로 실행되는 스크립트(prisma migrate deploy)가 있는지, 아니면 skip 됐는지 로그를 봐야 한다.

로컬에서 재현 가능한지 확인

로컬 DB를 새로 만들어서 같은 문제가 생기는지 본다. 만약 로컬에선 잘되고 운영에서만 안 되면, 환경 차이 때문일 가능성이 높다:

• DATABASE_URL 환경 변수가 정말 운영 DB를 가리키는가
• DB 접속 권한이 마이그레이션을 실행할 수 있는 수준인가
• 다른 인스턴스에서 동시에 마이그레이션을 실행하지 않았는가 (Prisma는 마이그레이션 lock을 쓰지만, 동시성 문제가 생길 수 있다)

반영 상태를 DB에서 직접 확인

# PostgreSQL
\d your_table

# MySQL
DESC your_table;

DB 클라이언트에서 테이블 정의를 본다. 새 컬럼이 정말 없는지, 아니면 있는데 애플리케이션이 못 보는 건지 확인한다.

이때 중요한 건 정확한 테이블명과 컬럼명이다. 혼동하기 쉬운 부분이다.

변경사항이 정말 배포됐는지 확인

배포된 schema.prisma 파일이 내 로컬 파일과 같은지 본다. 때로 CI/CD 파이프라인이 특정 파일을 빌드 결과물에 포함하지 않을 수 있다.

# 배포된 버전의 파일 내용 확인 (운영 서버 또는 배포 로그에서)
cat schema.prisma

마이그레이션 로그 추적

운영 환경 로그에서 마이그레이션이 실제로 돌았는지 본다:

# 배포 로그에서
# "prisma migrate deploy" 실행 여부
# 마이그레이션 적용 결과 메시지

만약 로그에 기록이 없으면, 배포 스크립트에서 이 단계가 빠졌거나 조건부로 실행되는 걸 확인해야 한다.

실제 수정 전 기록해둘 것

• 현재 schema.prisma의 마지막 수정 시간
• prisma migrate status 출력
• DB에서 본 실제 테이블 정의
• 배포 로그에서 마이그레이션 부분

이 네 가지를 남겨두면 다음에 같은 문제가 생겼을 때 원인을 빠르게 좁힐 수 있다. 작은 증거들이 모이면 원인은 자연스럽게 명확해진다.