운영 서버에서 Prisma 마이그레이션 적용하기 전 확인 사항

로컬에서 prisma migrate dev로 개발하다가 운영 서버에 처음 배포하면 생각보다 챙길 게 많다. 운영에서는 migrate dev가 아닌 migrate deploy를 써야 하고, 실패했을 때 되돌리기가 까다롭다.

migrate dev vs migrate deploy

prisma migrate dev는 개발용이다. shadow database를 만들고 draft migration을 생성한다. 운영 서버에서는 반드시 prisma migrate deploy를 써야 한다.

npx prisma migrate deploy

이 명령은 prisma/migrations/ 안에 있는 마이그레이션 파일 중 _prisma_migrations 테이블에 아직 적용되지 않은 것만 순서대로 실행한다. 이미 적용된 건 건너뛴다.

적용 전 확인 사항

1. 백업이 있는가. 컬럼 삭제나 타입 변경이 포함된 마이그레이션은 데이터 손실이 생길 수 있다. pg_dump로 스냅샷을 먼저 뜨고 진행한다.

2. 마이그레이션 파일이 Git에 있는가. prisma/migrations/ 디렉토리 전체가 커밋돼야 서버에서도 같은 파일로 적용된다. 개발 중 자동 생성된 파일을 커밋하지 않고 넘어가는 실수가 많다.

3. DATABASE_URL이 운영 DB를 가리키는가. 환경변수를 확인한다. 로컬 DB를 가리키고 있으면 운영에 아무 변화도 없다.

적용 후 확인

sudo journalctl -u 앱서비스명 -n 80 --no-pager
sudo ss -lntp | grep 5432

앱을 재시작한 뒤 Prisma 클라이언트가 새 스키마로 쿼리하는지 로그로 확인한다. 컬럼이 없다는 에러가 나오면 마이그레이션이 적용 안 됐거나 Prisma Client가 재생성(prisma generate)되지 않은 것이다.

롤백이 없다

Prisma는 자동 롤백을 지원하지 않는다. 실패한 마이그레이션은 수동으로 되돌려야 한다. 되도록 컬럼 삭제보다 nullable로 두었다가 나중에 제거하는 방식을 쓰고, 큰 스키마 변경은 트래픽이 적은 시간대에 진행한다.