Prisma Migrate와 Knex로 DB 마이그레이션 관리

소개

데이터베이스 마이그레이션은 스키마 변경을 일관되게 적용하고 되돌리는 작업이다. 작은 서비스라도 스키마 변화는 복잡성을 유발하므로 체계적 관리가 필요하다. 본문에서는 Prisma Migrate 사용법과 Knex 마이그레이션 예제를 통해 Node 환경에서 적용 가능한 Node DB 마이그레이션 전략을 제시한다.

마이그레이션 개념 정리

마이그레이션의 목적

스키마 버전 관리, 데이터 이관, 배포 간 일관성 확보가 핵심이다. 또한 롤백과 충돌 해결 방식에 따라 운영 안정성이 좌우된다.

주요 패턴

버전 기반 마이그레이션: 파일 순서로 변경 추적
모델 기반 마이그레이션: ORM 스키마 정의에서 자동 생성
데이터 마이그레이션: 스키마 변경과 함께 데이터 변형 수행

Prisma Migrate 사용법

Prisma는 스키마 중심 워크플로우를 제공한다. schema.prisma 파일로 모델을 정의하면 마이그레이션 파일을 생성하고 적용할 수 있다. Prisma Migrate는 데이터베이스 스키마를 선언적 방식으로 관리하므로 일관성이 높다.

기본 흐름

schema.prisma 수정
마이그레이션 생성: prisma migrate dev 또는 prisma migrate deploy
마이그레이션 적용

예제: schema.prisma

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

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

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

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

명령 예시

# 개발 환경에서 마이그레이션 생성 및 적용
npx prisma migrate dev --name add-post-content

# CI/CD 환경 적용(이미 생성된 마이그레이션 적용)
npx prisma migrate deploy

# 마이그레이트 상태 확인
npx prisma migrate status

주의점

Prisma Migrate는 스키마 선언을 중점으로 동작한다. 복잡한 데이터 변환은 별도 스크립트로 처리하는 것이 안전하다. 또한 프로덕션에서는 deploy 명령을 사용해 검증된 마이그레이션만 적용한다.

Knex 마이그레이션 예제

Knex는 쿼리 빌더이자 마이그레이션 도구를 제공한다. 파일 단위의 마이그레이션을 생성해 up/down 함수를 정의하는 방식이다. SQL 수준의 제어가 필요할 때 유용하다.

설정 파일 예

module.exports = {
  development: {
    client: 'pg',
    connection: process.env.DATABASE_URL,
    migrations: {
      directory: './migrations'
    }
  }
};

마이그레이션 파일 예

exports.up = function(knex) {
  return knex.schema.createTable('users', function(table) {
    table.increments('id').primary();
    table.string('email').unique().notNullable();
    table.string('name');
  });
};

exports.down = function(knex) {
  return knex.schema.dropTableIfExists('users');
};

사용 흐름

마이그레이션 생성: npx knex migrate:make create_users
적용: npx knex migrate:latest
롤백: npx knex migrate:rollback

장단점 비교

Prisma: 선언적 모델, 타입 안전, 자동 클라이언트 생성
Knex: 세밀한 SQL 제어, 유연한 마이그레이션 작성

Node DB 마이그레이션 전략

실무에서는 단일 툴보다 전략이 중요하다. 다음 항목을 고려해 체계화한다.

버전 관리와 코드 동기화

마이그레이션 파일은 코드 저장소에 포함되어야 한다. 코드와 스키마 변경은 동일한 PR로 관리하면 충돌을 줄일 수 있다.

CI/CD 연동

배포 파이프라인에서 마이그레이션 적용을 분리한다. 스테이징 환경에서 적용 검증 후 프로덕션에 적용하는 흐름이 바람직하다.

롤백과 데이터 보전

스키마 롤백은 항상 데이터 손실 위험을 동반한다. 다운 스크립트는 신중히 작성하고, 중요한 변경은 데이터 백업과 함께 배포한다.

데이터 마이그레이션 관리

데이터 변환이 필요한 경우, 마이그레이션과 별도의 마이그레이션 스크립트를 운영한다. 긴 작업은 청크 단위로 수행해 서비스 영향도를 줄인다.

테스트와 모니터링

마이그레이션 전후의 테스트와 모니터링이 필요하다. 스키마 적용 후 애플리케이션 레벨 테스트를 자동화하면 문제를 조기에 발견할 수 있다.

마무리

Prisma Migrate 사용법은 선언적 모델 관리에 적합하고, Knex 마이그레이션 예제는 세부 제어가 필요한 경우 강점이 있다. 최종 선택은 팀의 요구와 기존 스택, 운영 역량을 기반으로 결정하는 것이 바람직하다. 안전한 배포와 데이터 보전을 최우선으로 하는 Node DB 마이그레이션 전략을 권장한다.

목차

소개