Prisma migration이 로컬에서는 되는데 서버에서 터질 때

로컬에서 완벽하게 동작하던 Prisma migration이 서버 배포 환경에서만 터지면 정말 답답하다. 이런 상황을 빠르게 진단하려면 문제를 크게 보지 말고, 각 단계별로 차이점을 찾아야 한다.

프로세스부터 확인하기

서버 환경의 문제는 보통 실행 환경의 차이에서 시작된다. 먼저 어떤 프로세스가 실행 중인지, 어떤 서비스가 열려 있는지 확인해야 한다.

sudo ss -lntp
df -h
sudo journalctl -n 80

この명령들은 현재 서버의 상태를 스냅샷처럼 보여준다. 디스크 용량 문제, 포트 충돌, 시스템 로그까지 한눈에 들어온다.

로컬과 서버의 차이를 명확히 하기

로컬에서는 괜찮은데 서버에서만 문제가 생기는 경우는 항상 환경 차이 때문이다. 데이터베이스 버전, Node.js 버전, 혹은 환경 변수가 다를 수 있다. 문제를 진단할 때는 이런 환경 변수들을 함께 기록해두는 게 좋다.

• 현재 DB 버전은 무엇인가
• 서버의 Node.js 버전은 로컬과 같은가
• .env 파일의 설정은 제대로 적용됐는가

마이그레이션 로그 읽기

Prisma 마이그레이션이 실패하면 CLI에 상세한 에러 메시지가 나온다. 이 메시지를 정확히 읽는 것만으로도 대부분의 경우 원인을 파악할 수 있다. 예를 들어:

• "Column 'xxx' doesn't exist" → 마이그레이션이 제대로 적용되지 않음
• "Permission denied" → DB 접근 권한 문제
• "Timeout" → DB 연결 문제

한 번에 하나씩 바꿔보기

서버 배포 환경에서는 여러 설정을 동시에 바꾸면 원인 추적이 매우 어려워진다. 한 번에 하나의 설정만 변경하고, 그 결과를 확인하는 방식으로 접근하는 게 훨씬 빠르다.

1. 현재 상태를 기록한다.
2. 한 가지만 바꾼다.
3. 로그를 확인한다.
4. 실패했으면 되돌린다.

이 리듬을 유지하면 작은 확인들이 쌓여서 자연스럽게 원인에 도달한다.