본문으로 건너뛰기

Prisma 마이그레이션 가이드

이 문서는 DTA-WIDE 프로젝트에서 Prisma 스키마를 작성한 후 데이터베이스에 변경사항을 반영하는 방법을 설명합니다.

1. 마이그레이션 개요​

Prisma 마이그레이션은 schema.prisma 파일의 변경사항을 데이터베이스 스키마에 적용하는 과정입니다. 마이그레이션은 버전 관리되어 Git으로 추적되며, 모든 환경에서 일관된 데이터베이스 스키마를 유지하는 데 도움이 됩니다.

2. 개발 초기 단계에서의 스키마 관리​

개발 초기 단계에서는 마이그레이션 이력 관리보다 빠른 스키마 변경이 중요할 수 있습니다. 이 경우 prisma db push 명령어를 사용하면 마이그레이션 파일 없이 스키마 변경사항을 직접 데이터베이스에 적용할 수 있습니다.

2.1 db push 사용하기​

npx prisma db push

이 명령어는:

  • 마이그레이션 이력을 관리하지 않고 schema.prisma의 변경사항을 직접 데이터베이스에 적용합니다
  • 스키마와 데이터베이스 간의 차이를 감지하고 필요한 변경만 수행합니다
  • 개발 초기 단계나 프로토타이핑에 적합합니다
  • 데이터 손실이 발생할 수 있는 변경(예: 컬럼 삭제)에 대해 확인 메시지를 표시합니다

장점:

  • 빠른 개발 속도: 마이그레이션 파일 생성 단계를 건너뛰고 바로 변경사항을 적용할 수 있습니다
  • 유연성: 개발 중에 스키마를 자주 변경할 때 유용합니다
  • 간소화된 워크플로: 마이그레이션 이력을 신경 쓰지 않아도 됩니다

참고: 프로젝트가 성숙 단계에 접어들면 prisma migrate로 전환하여 마이그레이션 이력을 관리하는 것이 좋습니다.

2.2 db push와 데이터 보존​

기본적으로 db push는 데이터를 최대한 보존하려고 시도합니다. 데이터 손실 위험이 있는 경우 확인 메시지를 표시하며, 강제로 적용하려면 --force-reset 플래그를 사용할 수 있습니다:

npx prisma db push --force-reset

주의: --force-reset 옵션은 데이터베이스를 초기화하므로 모든 데이터가 손실됩니다!

2.3 db push와 클라이언트 생성​

db push 명령어는 자동으로 Prisma 클라이언트를 재생성합니다. 따라서 스키마를 변경하고 db push를 실행한 후에는 별도로 prisma generate를 실행할 필요가 없습니다.

클라이언트만 업데이트하려면 다음 명령어를 사용하세요:

npx prisma generate

3. 마이그레이션 명령어​

마이그레이션 이력 관리가 필요한 경우, 다음 명령어를 사용할 수 있습니다:

3.1 개발 환경에서 마이그레이션 생성 및 적용​

npx prisma migrate dev --name 마이그레이션_이름

이 명령어는 다음 작업을 수행합니다:

  • schema.prisma 파일의 변경사항을 기반으로 새로운 마이그레이션 파일 생성
  • 생성된 마이그레이션을 개발 데이터베이스에 즉시 적용
  • Prisma 클라이언트 재생성

팁: 마이그레이션 이름은 변경 내용을 명확하게 설명하는 의미 있는 이름을 사용하세요. 예: add_user_table, update_post_schema, add_user_role_column

3.2 마이그레이션 생성만 하기 (SQL 수동 편집)​

npx prisma migrate dev --create-only --name 마이그레이션_이름

이 명령어는:

  • 마이그레이션 SQL 파일만 생성하고 실행하지 않습니다
  • SQL 파일을 수동으로 편집할 수 있는 기회를 제공합니다
  • prisma/migrations/[타임스탬프]_마이그레이션_이름 디렉토리에 migration.sql 파일을 생성합니다

SQL 파일을 수정한 후, 다음 명령어로 마이그레이션을 적용합니다:

npx prisma migrate dev

3.3 프로덕션 환경에서 마이그레이션 적용​

npx prisma migrate deploy

이 명령어는:

  • CI/CD 파이프라인이나 프로덕션 환경에서 사용합니다
  • 아직 적용되지 않은 모든 마이그레이션을 순차적으로 안전하게 적용합니다
  • 데이터베이스를 초기화하거나 재설정하지 않습니다
  • 프로덕션 환경에 적합한 안전한 명령어입니다

3.4 마이그레이션 상태 확인​

npx prisma migrate status

이 명령어는:

  • 현재 데이터베이스에 적용된 마이그레이션의 상태를 표시합니다
  • 어떤 마이그레이션이 적용되었고 어떤 것이 대기 중인지 확인할 수 있습니다
  • 마이그레이션 이력을 확인할 수 있습니다

3.5 데이터베이스 시각화 및 탐색​

npx prisma studio

이 명령어는:

  • 브라우저 기반의 GUI 도구를 실행합니다
  • 데이터베이스 테이블 및 레코드를 시각적으로 확인하고 편집할 수 있습니다
  • 스키마 변경 후 데이터 상태를 확인하는 데 유용합니다

3.6 Prisma 클라이언트 재생성​

npx prisma generate

이 명령어는:

  • schema.prisma 파일을 기반으로 Prisma 클라이언트를 재생성합니다
  • 마이그레이션 후 자동으로 실행되지만, 스키마 변경 후 클라이언트만 업데이트하려는 경우 수동으로 실행할 수 있습니다

4. DTA-WIDE 프로젝트에서의 마이그레이션 관리​

4.1 MigrationService 사용​

프로젝트에는 마이그레이션을 관리할 수 있는 MigrationService가 구현되어 있습니다:

// 애플리케이션 시작 시 마이그레이션 실행
const migrationService = app.get(MigrationService);
await migrationService.runMigrations();

4.2 MigrationService 주요 메서드​

MigrationService는 다음과 같은 메서드를 제공합니다:

  1. runMigrations(): 데이터베이스 마이그레이션을 실행합니다.
  2. createMigration(name: string): 새 마이그레이션을 생성합니다 (개발 환경에서만 가능).
  3. getMigrationHistory(): 마이그레이션 이력을 조회합니다.

5. 마이그레이션 모범 사례​

5.1 마이그레이션 계획​

  • 대규모 스키마 변경은 작은 단계로 나누어 여러 마이그레이션으로 진행하세요.
  • 프로덕션 환경에 배포하기 전에 개발 및 스테이징 환경에서 마이그레이션을 테스트하세요.
  • 데이터 손실이 발생할 수 있는 변경(예: 컬럼 삭제)은 신중하게 계획하세요.

5.2 마이그레이션 검토​

  • 생성된 SQL 파일을 검토하여 의도한 변경사항이 올바르게 반영되었는지 확인하세요.
  • 특히 프로덕션 환경에 적용하기 전에 마이그레이션 롤백 전략을 고려하세요.

5.3 팀 협업​

  • 마이그레이션 파일은 Git에 커밋하고 팀원들과 공유하세요.
  • 여러 개발자가 동시에 스키마를 변경할 때는 마이그레이션 충돌에 주의하세요.

5.4 개발 단계별 접근 방식​

  • 초기 개발/프로토타이핑: prisma db push를 사용하여 빠르게 반복하세요.
  • 개발 안정화 단계: prisma migrate dev로 전환하여 마이그레이션 이력을 관리하세요.
  • 프로덕션 배포: prisma migrate deploy를 사용하여 안전하게 변경사항을 적용하세요.

6. 문제 해결​

6.1 마이그레이션 초기화​

개발 환경에서 문제가 발생한 경우 데이터베이스를 초기화할 수 있습니다:

npx prisma migrate reset

주의: 이 명령어는 데이터베이스를 삭제하고 다시 생성한 후 모든 마이그레이션을 적용합니다. 모든 데이터가 손실됩니다!

6.2 일반적인 문제​

  • 드리프트 감지: 데이터베이스 스키마가 마이그레이션 이력과 일치하지 않는 경우 발생합니다. 개발 환경에서는 --create-only 옵션을 사용하고 SQL을 수동으로 편집하거나 prisma db push를 사용하여 해결할 수 있습니다.
  • 외래 키 제약 조건: 관계가 있는 테이블을 삭제할 때는 순서에 주의하세요.
  • 타입 변환: 컬럼 타입을 변경할 때 데이터 변환 방법을 고려하세요.

7. 관련 문서​

TBD