DB 마이그레이션 파일을 Git에 올려야 하는 이유

Prisma를 처음 쓸 때 prisma/migrations 폴더가 자꾸 커지는 게 거슬려서 .gitignore에 넣으면 어떨까 생각했던 적이 있다. 찾아보니 그렇게 하면 안 되는 이유가 명확했다.

마이그레이션 파일이 하는 일

npx prisma migrate dev를 실행하면 prisma/migrations/<timestamp>_<name>/migration.sql 파일이 생긴다. 이 파일은 해당 시점에 DB 스키마를 어떻게 바꿔야 하는지 기술한 SQL이다. Prisma는 _prisma_migrations 테이블에 이미 적용된 마이그레이션 목록을 저장하고, 아직 실행되지 않은 파일만 골라서 순서대로 실행한다.

마이그레이션 파일이 없으면 prisma migrate deploy(운영 배포 시 쓰는 명령)가 실행할 SQL을 찾지 못한다.

# 운영 배포 전 확인
npx prisma migrate status
# → 적용된 마이그레이션과 미적용 마이그레이션 목록이 나온다

# 운영 DB에 미적용 마이그레이션 실행
npx prisma migrate deploy

Git에서 제외하면 어떤 일이 생기나

파일이 Git에 없으면 다른 팀원이나 CI 서버가 migrate deploy를 실행할 때 어떤 SQL을 실행해야 하는지 알 수 없다. 결국 스키마 파일(schema.prisma)과 실제 DB 상태가 일치하는지 수동으로 확인해야 하는 상황이 된다.

혼자 작업하는 경우에도 마찬가지다. 로컬 DB를 날리고 다시 만들거나, 새 환경에서 시작할 때 마이그레이션 파일이 없으면 migrate dev가 이미 있는 것처럼 처리하지 못하고 스키마 전체를 새로 밀어버릴 수 있다.

편집이 생기는 상황과 주의사항

마이그레이션 파일은 한 번 커밋하면 수정하지 않는 게 원칙이다. 이미 운영에 적용된 파일을 고치면 Prisma가 해시를 검증할 때 불일치로 배포가 멈춘다.

# 이미 적용된 마이그레이션을 실수로 수정했다면
npx prisma migrate resolve --rolled-back 20240601000000_add_user_table
# 또는 재적용
npx prisma migrate resolve --applied 20240601000000_add_user_table

스키마를 고치고 싶으면 새 마이그레이션 파일을 만들면 된다. migrate dev --name fix_column_type 식으로 이름을 붙이면 변경 내역 추적이 쉬워진다.

결론은 간단하다. 마이그레이션 파일은 DB 변경 이력이고, Git은 이력 관리 도구다. 둘을 같이 쓰는 게 맞다.