[Prisma7] 8편. Prisma 데이터베이스 동기화(Migration & Sync)실습 : 개발 → 운영

반응형

 

8편. Prisma 데이터베이스 동기화(Migration & Sync) 실습 : 개발 → 운영

 

📚 목차
1. Prisma에서 DB 동기화의 핵심 개념
2. 개발용 초기 DB 구축 (migrate dev)
3. 개발 DB 스키마 변경 관리 방법
4. 환경 변수 기반의 안전한 연결 관리와 자동 배포 프로세스

 

1. Prisma에서 DB 동기화의 핵심 개념

Prisma에서 데이터베이스 동기화를 올바르게 이해하려면,

“명령어별 역할 분리”와 함께 “schema → migration → DB → Client”의 흐름을 정확히 구분해야 합니다.

 

🔷 Prisma DB 동기화 명령어 역할 정리

명령어	환경	역할
migrate dev	개발	schema.prisma 변경 사항을 기반으로 마이그레이션 생성 → 개발 DB 반영 ※ Prisma 7에서는 더이상 Prisma Client를 자동 생성하지 않는다.
migrate deploy	운영	이미 생성된 마이그레이션 파일을 운영 DB에 순차적으로 적용 (Client 생성 ❌)
db push	실험 / PoC	마이그레이션 파일 없이 스키마를 DB에 즉시 반영 (Client 생성 ❌)
db pull	개발	기존 DB 구조를 읽어 schema.prisma로 변환 (역공학, Client 생성 ❌)
generate	모든 환경	schema.prisma를 기준으로 Prisma Client 생성 (DB 변경 없음)

 

Prisma에서 DB 동기화와 Prisma Client 생성은 개념적으로 분리된 책임이다.

▸ DB 구조 변경: migrate 명령어 담당
▸ 코드 타입 생성: generate 명령어 담당
▸ Prisma 7에서는 migrate dev 시 자동 generate를 하지 않으므로 반드시 각각 실행하는 것이 안전합니다.

# 개발
npx prisma migrate dev --name add_user_status
npx prisma generate   # 안전 장치

# 운영
npx prisma migrate deploy
npx prisma generate

 

🔷 prisma generate를 명시적으로 실행해야 하는 상황

1. Prisma Client output 경로를 커스터마이징한 경우

기본 경로(node_modules)가 아닌 별도 경로에 Client를 생성하면, 자동 생성 로직이 경로를 오인하거나 누락할 수 있습니다.

명시적 실행을 통해 정확한 위치에 타입을 주입해야 합니다.

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

 

2. Schema 파일은 수정되었으나 DB 구조는 변하지 않을 때

DB 테이블 구조와 상관없이 Prisma의 동작 방식만 바꿀 때 필요합니다.

▸ enum 값의 순서 변경 또는 내부적인 타입 정의 수정
▸ previewFeatures 활성화/비활성화 (예: typedSql, driverAdapters 등)
▸ generator 옵션(엔진 타입 등) 변경

 

3. CI/CD 배포 파이프라인 (가장 중요)

운영 환경에서 실행하는 migrate deploy는 DB 상태만 업데이트할 뿐, 애플리케이션이 사용할 Client 라이브러리를 빌드하지 않습니다. 따라서 배포 스크립트에는 항상 두 명령어가 포함되어야 합니다.

npx prisma migrate deploy
npx prisma generate

 

2. 개발용 초기 DB 구축 (migrate dev)

스키마 구조 참고: [Prisma7] 1편. 개발환경 구축과 프로젝트 초기화 (Node.js + Prisma 7)

 

Prisma Migrate는 단순히 스키마를 적용하는 것에 그치지 않고, 스키마 설계부터 변경 이력 관리, DB 동기화를 통합 수행하는 설계 중심 도구입니다.

 

🔷 최초 마이그레이션 생성 및 반영

npx prisma migrate dev --name init_schema
npx prisma generate   # 명시적

 

명령어 실행 시 내부 동작:

▸ 스키마 분석: schema.prisma 파일의 변경 사항을 감지합니다.
▸ SQL 생성: 변경 사항을 바탕으로 prisma/migrations 폴더 내에 SQL 마이그레이션 파일을 생성합니다.
▸ DB 즉시 반영: 생성된 SQL을 개발 환경의 데이터베이스에 즉시 적용합니다.
▸ Client 재생성: 변경된 스키마에 맞춰 Type-safe한 Prisma Client를 자동 업데이트합니다. (npx prisma generate 포함)

 

📌운영(Production) 환경 주의

migrate dev는 개발 편의를 위해 DB를 초기화(Reset)할 가능성이 있으므로, 운영 DB에서는 절대 사용하지 마세요.

운영 환경에서는 npx prisma migrate deploy를 사용해야 합니다.

 

디렉터리 구조 예시

prisma/
 └─ migrations/
    └─ 20260101_init_schema/
       └─ migration.sql

 

🔷 동일한 명령을 다시 실행할 경우

1. schema.prisma에 변경이 없는 경우

이미 DB와 스키마가 일치하는 상태라면 아무런 작업도 수행하지 않으며 안전합니다. 이때 --name 옵션은 무시됩니다.

npx prisma migrate dev --name init_schema

결과
Already in sync, no schema change or pending migration was found.

 

2. schema.prisma에 변경이 있는 경우

" 3. 개발 DB 스키마 변경 관리 방법" 참고

반응형

 

3. 개발 DB 스키마 변경 관리 (Prisma Migrate)

🔷 Prisma Migrate의 내부 동작 흐름 이해하기

npx prisma migrate dev 실행 시 Prisma는 다음 순서로 동작합니다.

 

1단계: 현재 상태 파악 (Scanning)

▸ 실제 DB 구조 확인: 현재 연결된 데이터베이스(PostgreSQL 등)의 테이블, 컬럼, 인덱스 상태를 스캔하여 스냅샷을 생성합니다.
▸ 마이그레이션 이력 확인: DB 내부의 _prisma_migrations 테이블을 조회하여 이미 적용된 마이그레이션 파일들이 무엇인지 확인합니다.

 

2단계: 차이점 계산 (Diffing)

▸ Prisma는 schema.prisma 파일과 1단계에서 파악한 현재 DB 상태를 비교합니다.
▸ Shadow Database 활용: 이 과정에서 Prisma는 임시 데이터베이스(Shadow DB)를 생성하여, 현재까지의 마이그레이션 파일들이 유효한지, 새로운 변경 사항이 충돌을 일으키지는 않는지 안전하게 검증합니다.
▸ 분석 대상: 테이블 신규 추가, 필드 타입 변경, 인덱스 및 제약 조건(Constraints) 수정 등.

 

3단계: 변경 사항 처리 (Execution)

비교 결과 변경 사항이 감지되면 다음 작업을 순차적으로 수행합니다.

1. 마이그레이션 파일 생성:

   변경 내용을 SQL 문으로 변환하여 prisma/migrations 폴더 내에 타임스탬프 기반의 디렉터리

   (예: 20260108_add_user_status)를 생성합니다.
2. 데이터베이스 반영:

   생성된 SQL을 실제 개발 데이터베이스에 즉시 실행합니다.
3. 이력 업데이트:

    _prisma_migrations 테이블에 해당 마이그레이션의 성공 여부와 실행 시간을 기록합니다.
4 .Prisma Client 재생성 (Artifacts Update):

    변경된 스키마에 맞춰 최신 타입 정의가 포함된 Prisma Client를 자동으로 생성(generate)합니다.

 

 

🔷 예시: User 모델에 status 컬럼 추가

model User {
 ... 생략
  status      String     @default("ACTIVE")
  // Relations
 ... 생략
}

>> npx prisma migrate dev --name init

결과:
Applying migration `20260108002217_init`

The following migration(s) have been created and applied from new schema changes:

prisma\migrations/
  └─ 20260108002217_init/
    └─ migration.sql

Your database is now in sync with your schema.
┌─────────────────────────────────────────────────────────┐
│  Update available 7.1.0 -> 7.2.0                        │
│  Run the following to update                            │
│    npm i --save-dev prisma@latest                       │
│    npm i @prisma/client@latest                          │
└─────────────────────────────────────────────────────────┘

>> npx prisma generate

결과:
✔ Generated Prisma Client (7.1.0) to .\generated in 164ms

개발DB에 status 칼럼 추가 결과 화면

 

🔷 실무 권장 네이밍 규칙

Prisma 마이그레이션은 이름이 아닌 타임스탬프(ID)를 기준으로 순서를 결정합니다.

하지만 협업 시 동료가 변경 내용을 쉽게 파악할 수 있도록 행위 + 대상 형태의 직관적인 이름을 사용하는 것이 권장됩니다.

유형	권장 예시	설명
초기 생성	init 또는 initial_schema	프로젝트 시작 시 기본 테이블 및 스키마를 설정
컬럼 추가	add_user_status	특정 테이블에 새로운 필드를 추가
컬럼 수정	alter_post_content_type	컬럼 타입 변경 또는 제약 조건 수정
삭제 작업	remove_old_logs	더 이상 사용하지 않는 테이블 또는 컬럼 제거
인덱스 추가	add_idx_user_email	조회 성능 개선을 위한인덱스 생성

 

4. 환경 변수 기반의 안전한 연결 관리와 자동 배포 프로세스

🔷 운영 DB 연결 관리의 핵심: "격리 및 주입"

운영 DB의 보안과 안정성을 위해 상시 연결을 지양하고, 배포 시점에 시스템 환경 변수를 통해 동적으로 연결하는 방식을 원칙으로 합니다.

 

▸ 로컬 환경

    .env 파일을 활용하여 로컬 DB(127.0.0.1)에 접근하며, 자유롭게 prisma migrate dev를 실행해 스키마를 설계합니다.
▸ 운영 환경

    보안을 위해 설정 파일(Secret)을 Git에 포함하지 않습니다.

    오직 서버 인스턴스나 CI/CD 파이프라인(GitHub Actions, Jenkins 등)의 시스템 환경 변수를 통해서만 DATABASE_URL을 주입합니다.

 

🔷 운영 DB 반영 및 배포 워크플로우

운영 환경에서는 데이터 일관성과 안전을 위해 반드시 다음 절차를 따릅니다.

특히 운영 DB에는 데이터 손실 위험이 있는 migrate dev 대신, 실행되지 않은 마이그레이션 파일만 안전하게 적용하는 migrate deploy 명령어를 사용해야 합니다.

# 1. 운영 DB URL 주입
# export DATABASE_URL=...
# powershell 명령어
$env:DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:5433/prisma_op?schema=public"

# 2. Prisma Client 생성
npx prisma generate

# 3. 운영 DB 마이그레이션 적용
npx prisma migrate deploy

운영db 배포 화면

운영 DB 반영 결과

 

 

---

※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.

반응형