Prisma Migrate로 DB 변경사항 깔끔하게 관리하기

🔥 들어가는 말

개발을 하다 보면 데이터베이스 스키마 변경이 필요할 때가 많다. 새로운 기능을 추가하거나, 기존 테이블 구조를 수정하는 등 다양한 이유로 테이블을 변경해야하기 때문이다. 하지만 변경 사항을 수동으로 관리하면 여러 문제를 겪을 수 있다.

• DB 변경 사항을 추적하기 어렵다 → 누가 언제 어떤 변경을 했는지 기록이 남지 않는다
• 환경별 일관성이 부족하다 → 로컬, 스테이징, 프로덕션 환경 간 스키마가 다를 수 있다

이런 문제를 해결하기 위해 migration 도구를 사용한다.
기존에는 TypeORM을 사용하여 migration 작업을 처리해주었었는데, 회사에서 Prisma를 사용하게 되면서 Prisma Migration을 적용할 기회가 생겼다.

이번 글에서는

1. 데이터베이스 변경 사항을 기준으로 Prisma Schema를 업데이트하고 마이그레이션을 적용하는 방법

2. Prisma Schema를 기준으로 데이터베이스를 업데이트하고 마이그레이션을 적용하는 방법

   이 두 가지를 소개하고, Prisma Migrate를 활용한 데이터베이스 마이그레이션 관리법을 설명하고자 한다.

---

✅ 데이터베이스 변경 사항 기반 마이그레이션 생성

1. 마이그레이션 폴더 생성

우선 prisma/migrations 디렉토리에 마이그레이션 폴더를 생성한다.
- 예시: 0_db2schema
- 마이그레이션 파일의 순서가 중요하므로 번호는 순차적으로 증가해야 한다.

2. DB 변경 사항 기반 diff 마이그레이션 파일 생성

$ npx prisma migrate diff --from-schema-datamodel prisma/schema.prisma  --to-schema-datasource prisma/schema.prisma --script > prisma/migrations/0_db2schema/migration.sql 

• 이 명령어는 DB와 Prisma 스키마를 비교하여 변경된 사항을 자동으로 감지하고, SQL 마이그레이션 파일을 생성한다.
• 그렇게 출력된 SQL 파일은 직접 검토한 후 적용할 수 있어, 보다 안전하게 변경 사항을 관리할 수 있다.

3. 생성된 마이그레이션 파일 적용

npx prisma migrate resolve –-applied {마이그레이션 이름}

• _prisma_migrations 테이블이 생성되며, 마이그레이션 정보는 해당 테이블에 적용되어 마이그레이션 이력을 관리하게 된다

4. 데이터베이스에서 스키마 업데이트 반영

$ npx prisma db pull

db를 바탕으로 schema.prisma를 업데이트 해준다.

5. schema.prisma 포맷팅

DB에서는 일반적으로 snake_case를 사용하지만, 코드에서는
• 모델명: PascalCase (User, Order)
• 필드명: camelCase (userId, createdAt)
형식을 따르는 것이 일반적이다.

그러나 db pull 명령어를 실행하면 DB의 테이블 및 컬럼명을 그대로 가져와 모델을 생성하기 때문에, snake_case가 적용된다.

이를 컨벤션에 맞춰 변환하기 위해서는 model에 @@map()을 사용하여 우리가 원하는 형식으로 매핑을 해줘야한다

그런데 직접 수정해야 할 모델과 필드의 수가 너무 많고 그걸 수정하는 과정에서의 휴먼에러도 방지하기 위해
prisma-case-format라는 패키지를 사용하여 이를 한번에 수정해주도록 만들어 주었다

package.json 스크립트 추가

"scripts": {
	"prisma:format": "npx prisma-case-format -f prisma/schema.prisma --table-case=pascal,singular --field-case=camel --map-field-case=snake"
}

스크립트 실행

$ npm run prisma:format

• 실행 후 schema.prisma의 모델 및 필드명이 컨벤션에 맞게 자동 정리된다.

6. Prisma Client 코드 생성

npx prisma generate

• Prisma Client를 최신 상태로 생성하여 사용할 준비를 한다.

---

✅ Prisma 스키마 기반 마이그레이션 생성 및 적용

1. schema.prisma 업데이트

• schema.prisma 파일에서 모델을 수정하거나 추가한다.
  

2. schema.prisma 포맷팅

$ npm run prisma:format

3. schema.prisma 업데이트 후 마이그레이션 파일 생성

$ npx prisma migrate dev –create-only

• 새로운 마이그레이션 폴더가 {timestamp}_{마이그레이션 이름} 형식으로 자동 생성된다
• 네이밍 규칙에 맞게 폴더 이름을 변경해준다.
  

4. 마이그레이션 파일을 데이터베이스에 적용

$ npx prisma migrate dev

---

🔥 마무리

• DB 변경 사항을 기준으로 Prisma Schema를 업데이트하는 방법과 Prisma Schema를 기준으로 DB를 업데이트하는 방법을 비교하며 정리했다.
• Prisma Migrate를 활용하면 일관된 마이그레이션 관리가 가능하고, 환경별 차이를 최소화할 수 있다.

이제 프로젝트에서 Prisma Migration을 활용해 일관된 스키마 변경 관리를 시작해보자! 🚀