Prisma schema를 수정한 뒤 빠뜨리기 쉬운 단계들

Prisma schema를 수정하면 그 뒤에 해야 할 일이 순서대로 있다. 이 순서를 빠뜨리거나 건너뛰면 배포 후에야 에러가 나는 경우가 많다.

1. validate — 문법 확인

npx prisma validate

schema 파일의 문법이 맞는지 먼저 확인한다. 필드 타입 오류, 관계 선언 실수 같은 게 여기서 잡힌다. migrate 전에 반드시 통과시킨다.

2. migrate — DB에 실제 변경 반영

npx prisma migrate dev --name add_user_avatar

--name은 마이그레이션 파일 이름에 붙는다. 나중에 migrations/ 폴더를 볼 때 어떤 변경인지 알 수 있도록 구체적으로 쓴다.

현재 마이그레이션 상태를 보려면:

npx prisma migrate status

DATABASE_URL이 올바른 환경을 가리키고 있는지 확인하고 실행한다. 로컬 DB에 migrate dev를 실행해야 하는데 프로덕션 URL이 환경변수에 들어 있으면 큰일이 난다.

3. generate — Prisma Client 재생성

npx prisma generate

schema가 바뀌었으면 Client도 다시 생성해야 한다. 이걸 빠뜨리면 새 필드를 코드에서 참조할 때 타입 에러가 나거나, 런타임에 undefined가 반환된다.

package.json에 postinstall hook을 걸어두면 npm install 시 자동으로 실행된다.

"scripts": {
  "postinstall": "prisma generate"
}

배포 환경에서 주의할 점

운영 DB에는 migrate dev 대신 migrate deploy를 쓴다.

npx prisma migrate deploy

migrate deploy는 pending 상태의 마이그레이션을 순서대로 적용하며, 새 마이그레이션 파일을 만들지 않는다. CI/CD 파이프라인에 이 명령을 넣어두면 배포 시 자동으로 반영된다.

백업은 migrate 전에

DB 구조를 바꾸는 마이그레이션(컬럼 삭제, NOT NULL 추가 등)은 되돌리기 어렵다. 운영 DB라면 migrate 전에 스냅샷이나 pg_dump를 남겨두는 게 안전하다.

pg_dump -Fc mydb > mydb_before_migration_$(date +%Y%m%d).dump

순서를 지키지 않아서 생기는 문제보다, 이 루틴을 습관화하는 비용이 훨씬 작다.