2026년 최신 Prisma ORM으로 데이터베이스 마이그레이션 자동화하기

최신 버전의 Prisma는 성능이 엄청 좋아졌어요. 특히 대규모 스키마를 다룰 때 마이그레이션 생성 속도가 이전 버전보다 3배 이상 빨라졌고, PostgreSQL, MySQL, MongoDB 등 다양한 데이터베이스를 지원하면서도 일관된 인터페이스를 제공해요. 게다가 2026년 들어서는 AI 기반 스키마 최적화 제안 기능까지 추가되었거든요.

# 새 프로젝트 디렉토리 생성
mkdir my-prisma-project
cd my-prisma-project

# package.json 생성
npm init -y

# Prisma CLI를 개발 의존성으로 설치
npm install prisma --save-dev

# Prisma Client 설치 (실제 사용할 패키지)
npm install @prisma/client

# TypeScript 사용한다면 (선택사항)
npm install typescript ts-node @types/node --save-dev

# PostgreSQL 사용 시
npx prisma init --datasource-provider postgresql

# MySQL 사용 시
npx prisma init --datasource-provider mysql

# SQLite 사용 시 (로컬 테스트용)
npx prisma init --datasource-provider sqlite

# PostgreSQL 연결 정보
DATABASE_URL="postgresql://postgres:mypassword@localhost:5432/myappdb?schema=public"

# 또는 SQLite (간단하게 테스트할 때)
# DATABASE_URL="file:./dev.db"

.env 파일에는 민감한 정보가 들어가니까요, .gitignore에 꼭 추가하세요! 실수로 GitHub에 올리면 큰일나요. Prisma 초기화하면 자동으로 .gitignore에 추가되긴 하는데, 한 번 확인해보는 게 좋아요.

// Prisma Client 생성기 설정
generator client {
  provider = "prisma-client-js"
}

// 데이터베이스 연결 설정
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 여기부터 모델(테이블) 정의를 추가하면 됩니다
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
}

# Prisma Client 생성
npx prisma generate

# 데이터베이스 동기화도 함께 (테이블 생성)
npx prisma db push

package.json의 scripts에 "postinstall": "prisma generate"를 추가해두면요, npm install 할 때마다 자동으로 클라이언트가 생성돼요. 팀 프로젝트할 때 엄청 편해요!

# Prisma Studio 실행
npx prisma studio

# 브라우저에서 http://localhost:5555 자동으로 열림

// schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  posts     Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
}

1. 일대다 (One-to-Many)

model User {
  id    Int    @id @default(autoincrement())
  posts Post[] // 한 명의 유저가 여러 게시글 작성
}

model Post {
  id       Int  @id @default(autoincrement())
  authorId Int
  author   User @relation(fields: [authorId], references: [id])
}

2. 다대다 (Many-to-Many)

model Post {
  id         Int        @id @default(autoincrement())
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

3. 일대일 (One-to-One)

model User {
  id      Int      @id @default(autoincrement())
  profile Profile?
}

model Profile {
  id     Int  @id @default(autoincrement())
  userId Int  @unique
  user   User @relation(fields: [userId], references: [id])
}

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 사용자 모델
model User {
  id            String    @id @default(cuid())
  email         String    @unique
  name          String
  passwordHash  String    @map("password_hash")
  avatar        String?
  bio           String?   @db.Text
  role          UserRole  @default(USER)
  emailVerified Boolean   @default(false) @map("email_verified")
  createdAt     DateTime  @default(now()) @map("created_at")
  updatedAt     DateTime  @updatedAt @map("updated_at")
  
  posts         Post[]
  comments      Comment[]
  likes         Like[]
  
  @@index([email])
  @@map("users")
}

// 사용자 권한 열거형
enum UserRole {
  USER
  ADMIN
  MODERATOR
}

// 게시글 모델
model Post {
  id          String   @id @default(cuid())
  title       String
  slug        String   @unique
  content     String   @db.Text
  excerpt     String?  @db.VarChar(500)
  coverImage  String?  @map("cover_image")
  published   Boolean  @default(false)
  viewCount   Int      @default(0) @map("view_count")
  authorId    String   @map("author_id")
  publishedAt DateTime? @map("published_at")
  createdAt   DateTime @default(now()) @map("created_at")
  updatedAt   DateTime @updatedAt @map("updated_at")
  
  author      User       @relation(fields: [authorId], references: [id], onDelete: Cascade)
  comments    Comment[]
  likes       Like[]
  tags        PostTag[]
  
  @@index([slug])
  @@index([authorId])
  @@index([published, publishedAt])
  @@map("posts")
}

// 댓글 모델
model Comment {
  id        String   @id @default(cuid())
  content   String   @db.Text
  postId    String   @map("post_id")
  authorId  String   @map("author_id")
  parentId  String?  @map("parent_id")
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
  
  post      Post      @relation(fields: [postId], references: [id], onDelete: Cascade)
  author    User      @relation(fields: [authorId], references: [id], onDelete: Cascade)
  parent    Comment?  @relation("CommentReplies", fields: [parentId], references: [id])
  replies   Comment[] @relation("CommentReplies")
  
  @@index([postId])
  @@index([authorId])
  @@map("comments")
}

// 좋아요 모델
model Like {
  id        String   @id @default(cuid())
  userId    String   @map("user_id")
  postId    String   @map("post_id")
  createdAt DateTime @default(now()) @map("created_at")
  
  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
  post Post @relation(fields: [postId], references: [id], onDelete: Cascade)
  
  @@unique([userId, postId])
  @@index([postId])
  @@map("likes")
}

// 태그 모델
model Tag {
  id    String    @id @default(cuid())
  name  String    @unique
  slug  String    @unique
  posts PostTag[]
  
  @@map("tags")
}

// 게시글-태그 중간 테이블
model PostTag {
  postId String @map("post_id")
  tagId  String @map("tag_id")
  
  post Post @relation(fields: [postId], references: [id], onDelete: Cascade)
  tag  Tag  @relation(fields: [tagId], references: [id], onDelete: Cascade)
  
  @@id([postId, tagId])
  @@map("post_tags")
}

금액 계산이 필요한 프로젝트라면 Float 대신 Decimal을 반드시 써야 해요. Float는 부동소수점 오차 때문에 0.1 + 0.2가 0.3이 안 나올 수도 있거든요. 진짜 경험담이에요. 한번은 이거 때문에 결제 금액이 안 맞아서 진짜 식은땀 났어요...

• 복합 인덱스 활용
  WHERE 조건에 자주 함께 쓰이는 컬럼들은 복합 인덱스로 묶어주세요. 예를 들어 (published, createdAt)처럼요.
• 부분 인덱스 고려
  특정 조건의 데이터만 자주 조회한다면 PostgreSQL의 부분 인덱스를 쓰세요. 인덱스 크기를 줄일 수 있어요.
• TEXT vs VARCHAR 선택
  길이가 정해진 데이터면 VARCHAR(n), 제한 없으면 TEXT. PostgreSQL에선 성능 차이 거의 없지만 명시적이 좋아요.
• 정규화 vs 비정규화
  읽기가 훨씬 많은 데이터는 약간의 비정규화를 고려해보세요. viewCount처럼 집계 데이터를 미리 저장하는 거죠.

model Post {
  id           String @id @default(cuid())
  title        String
  // ... 다른 필드들
  commentCount Int    @default(0) @map("comment_count") // 비정규화!
  
  comments     Comment[]
}

// 댓글 생성/삭제 시 commentCount 업데이트 필요
// 이건 트리거나 애플리케이션 로직으로 처리

model Post {
  id        String    @id @default(cuid())
  title     String
  content   String
  deletedAt DateTime? @map("deleted_at") // null이면 활성, 값 있으면 삭제됨
  
  createdAt DateTime  @default(now()) @map("created_at")
  updatedAt DateTime  @updatedAt @map("updated_at")
  
  // 삭제되지 않은 게시글만 조회하는 인덱스
  @@index([deletedAt])
}

name: Deploy with Prisma Migration
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run Prisma Migration
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          
      - name: Deploy Application
        run: npm run deploy

FROM node:20-alpine

WORKDIR /app

# 의존성 복사 및 설치
COPY package*.json ./
COPY prisma ./prisma/
RUN npm ci

# Prisma 클라이언트 생성
RUN npx prisma generate

# 애플리케이션 코드 복사
COPY . .

# 빌드
RUN npm run build

# 시작 스크립트 생성
RUN echo '#!/bin/sh
npx prisma migrate deploy
npm start' > /app/start.sh
RUN chmod +x /app/start.sh

CMD ["/app/start.sh"]

{
  "scripts": {
    "db:dev": "prisma migrate dev",
    "db:deploy": "prisma migrate deploy",
    "db:reset": "prisma migrate reset --force",
    "db:seed": "prisma db seed",
    "db:studio": "prisma studio",
    
    "dev": "npm run db:dev && next dev",
    "build": "prisma generate && next build",
    "start": "npm run db:deploy && next start",
    
    "deploy:staging": "npm run build && npm run db:deploy",
    "deploy:prod": "npm run build && npm run db:deploy"
  },
  "prisma": {
    "seed": "ts-node prisma/seed.ts"
  }
}

// migrate-with-logging.ts
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

async function runMigration() {
  const startTime = Date.now();
  
  try {
    console.log('[마이그레이션] 시작:', new Date().toISOString());
    
    const { stdout, stderr } = await execAsync('npx prisma migrate deploy');
    
    const duration = Date.now() - startTime;
    
    console.log('[마이그레이션] 성공!');
    console.log('[소요 시간]', duration, 'ms');
    console.log('[출력]', stdout);
    
    // Slack이나 Discord에 알림 전송
    await sendNotification({
      status: 'success',
      duration,
      output: stdout
    });
    
  } catch (error) {
    console.error('[마이그레이션] 실패:', error);
    
    // 긴급 알림 전송
    await sendUrgentAlert({
      status: 'failed',
      error: error.message
    });
    
    process.exit(1);
  }
}

메인 브랜치를 pull 받은 직후에 마이그레이션을 생성하세요. 그리고 가능하면 한 번에 하나의 마이그레이션 작업만 진행하는 게 좋아요. 여러 기능을 동시에 개발하더라도 스키마 변경은 순차적으로 처리하는 거죠.

• 스키마 변경 내용: schema.prisma 파일의 변경사항이 의도한 대로인지 확인
• 마이그레이션 SQL: 생성된 SQL 파일이 안전한지, 데이터 손실 위험은 없는지 검토
• 하위 호환성: 기존 코드가 새 스키마에서도 작동하는지 확인
• 롤백 계획: 문제 발생 시 되돌릴 방법이 있는지 점검
• 데이터 마이그레이션: 기존 데이터 변환이 필요하다면 스크립트 검증

name: Deploy with Prisma Migration
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run Prisma Migration
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
      
      - name: Deploy Application
        run: npm run deploy

팀원들에게 절대로 프로덕션 DATABASE_URL을 공유하지 마세요! 로컬에서는 도커 컴포즈로 DB를 띄우거나, 별도의 개발 DB 서버를 사용하는 게 안전해요. 실수로 프로덕션 DB를 reset하면... 생각만 해도 끔찍하죠.

• 마이그레이션 히스토리 확인: prisma migrate status로 현재 상태를 먼저 체크하세요
• 충돌 파일 식별: migrations 폴더를 열어서 타임스탬프가 겹치는 파일이 있는지 확인해보세요
• 리셋 후 재생성: 개발 환경이라면 prisma migrate reset을 사용할 수 있어요
• 수동 병합: 프로덕션이라면 마이그레이션 파일을 직접 병합해야 해요

# 현재 마이그레이션 상태 확인
npx prisma migrate status

# 개발 환경: 리셋 후 새로 시작
npx prisma migrate reset
npx prisma migrate dev --name merge-migrations

# 프로덕션: 충돌 파일 수동 병합 후
npx prisma migrate resolve --applied "20260409120000_first_migration"
npx prisma migrate deploy

# 1. 현재 상태 확인
npx prisma migrate status

# 2. 실패한 마이그레이션 표시
npx prisma migrate resolve --rolled-back "20260409140000_failed_migration"

# 3. 데이터베이스 백업에서 복구
# (이 부분은 사용하는 DB에 따라 다름)

# 4. 수정된 마이그레이션 재실행
npx prisma migrate deploy

# 5. 검증
npx prisma migrate status

• 정기적인 검사: CI/CD 파이프라인에 prisma migrate diff 추가하세요
• 자동 감지 설정: pre-commit 훅을 사용해서 배포 전에 자동으로 체크할 수 있어요
• 베이스라인 생성: 기존 DB에 Prisma를 적용할 때는 --create-only 옵션을 활용하세요
• 수동 변경 추적: 누군가 DB를 직접 수정했다면 즉시 스키마 파일에 반영하세요

1. "Migration already applied"
→ 마이그레이션 히스토리 테이블이 꼬인 거예요. prisma migrate resolve로 상태를 정리하세요.

2. "Database is not empty"
→ 처음 마이그레이션 생성할 때 나오는데요. --skip-seed 옵션을 쓰거나 DB를 비우세요.

3. "Foreign key constraint failed"
→ 관계 설정이 잘못됐어요. 참조 무결성을 확인하고 순서를 조정해보세요.

4. "Column cannot be null"
→ 필수 컬럼 추가할 때 나오죠. 기본값을 설정하거나 일단 옵셔널로 만들어보세요.

5. "Unique constraint violation"
→ 유니크 제약 조건 때문이에요. 기존 데이터를 먼저 정리해야 해요.