02672025년 8월 8일

[Node.js] 데이터베이스 마이그레이션 완벽 가이드: 개념부터 Prisma 실습까지

시작하며

프로젝트를 하다 보면 “DB에 컬럼 하나만 추가해야지” 하고 직접 SQL을 작성해 변경하는 경우가 많다.

그런데 팀원마다 다른 SQL을 쓰거나, 개발 서버와 운영 서버 구조가 달라지는 순간…

버그와 데이터 꼬임이 한 번에 찾아온다.

이 문제를 깔끔하게 해결하는 방법이 바로 마이그레이션(Migration)이다.

마이그레이션은 데이터베이스의 변화를 코드로 관리하고,

모든 환경에서 동일한 구조를 유지할 수 있게 돕는 든든한 도구다.

이번 글에서는 마이그레이션이 무엇이고, 왜 필요한지, 그리고 실제로 어떻게 쓰는지까지 정리해본다.

마이그레이션의 정의

: 마이그레이션(Migration)은 데이터베이스의 구조(스키마) 변화를 코드로 기록하고, 이를 단계적으로 적용하는 작업을 말한다.

예를 들어, 컬럼을 추가하거나 삭제하고, 테이블을 새로 만드는 등의 작업을 마이그레이션으로 관리한다.

즉, “데이터베이스 설계의 이력 관리 도구”라고 이해하면 쉽다.

왜 필요한가?

마이그레이션을 쓰지 않는다면, 개발자는 직접 SQL을 작성해 DB를 수정해야 한다.

문제는 이렇게 되면:

누가, 언제, 어떤 변경을 했는지 추적하기 어렵다.
로컬/개발/운영 DB 구조가 서로 다를 수 있다.
여러 명이 개발하면 스키마가 꼬일 가능성이 크다.

반대로, 마이그레이션을 사용하면

변경 사항을 코드로 관리 → Git에 기록 가능
버전별 변경 내역 확인 → 롤백 가능
모든 환경에서 동일한 구조 유지 가능

마이그레이션의 동작 원리

대부분의 ORM(Prisma, Sequelize, TypeORM 등)은 다음 흐름으로 동작한다.

1) 스키마 변경

예: User 테이블에 profile_image 컬럼 추가

2) 마이그레이션 파일 생성

JavaScript

npx prisma migrate dev --name add-profile-image

→ 이 명령은 변경 사항을 기반으로 SQL 파일을 생성

3) DB에 적용

마이그레이션 파일이 순서대로 실행되면서 DB 구조 변경

4) 이력 저장

마이그레이션 내역이 DB 내부(_prisma_migrations 같은 테이블)에 기록

여러 명령어 사용법 가이드라인 (Prisma)

1) 초기 세팅(최초 스키마 반영 + 이력 관리 시작)

code

# schema.prisma 작성 후
npx prisma migrate dev --name init

2) 개발 중 빠르게 스키마 반영(이력 파일 없이 속도)

code

npx prisma db push

언제? 프로토타이핑·혼자 실험할 때
주의 운영 배포에는 부적합(마이그레이션 이력 X)

3) 변경사항을 이력과 함께 반영(팀 개발 표준)

code

npx prisma migrate dev --name add-profile-image

언제? 스키마 변경을 Git으로 공유·검토해야 할 때

4) 운영/스테이징에 배포(이미 만들어진 이력 적용)

code

# CI/CD 또는 서버에서
npx prisma migrate deploy

언제? PR 머지 후 배포 단계
주의 이 명령은 “이미 커밋된 마이그레이션”만 실행

5) 로컬 DB를 초기화하고 전 이력 재적용(파괴적)

code

npx prisma migrate reset

언제? 로컬 DB 꼬임/충돌 발생 시 리셋
주의 데이터 모두 삭제됨. 운영에서 절대 금지

6) 타입 안전 클라이언트 재생성

code

npx prisma generate

언제? schema 변경 후 VSCode 자동완성/타입 갱신 필요할 때
보통 migrate dev, db push가 끝나면 자동 실행되지만, 수동 실행해도 됨

7) 시드 데이터 넣기

code

# package.json에 "prisma": { "seed": "ts-node prisma/seed.ts" } 설정 후
npx prisma db seed

언제? 기본 관리자/테스트 데이터 자동 주입
팁 migrate reset 이후 자동으로 실행되게 설정 가능

8) 데이터 확인/수정용 UI

code

npx prisma studio

브라우저에서 테이블 조회/편집 가능(개발 단계에서 유용)

예시 (Prisma 기준)

1) Prisma schema 변경

code

model User {
  id           Int     @id @default(autoincrement())
  email        String  @unique
  name         String?
  profileImage String? // 새로 추가
}

2) 마이그레이션 실행

code

npx prisma migrate dev --name add-profile-image

3) 결과

/prisma/migrations/날짜_add-profile-image/ 폴더 생성
안에는 DB 변경을 위한 SQL 파일이 들어 있음
실행 시 DB 스키마 업데이트

마이그레이션 vs 시드 데이터

마이그레이션: DB 구조(스키마)를 변경하는 것
시드 데이터(Seed Data): 초기 데이터를 DB에 넣는 것(예: 기본 관리자 계정 생성, 테스트 데이터 삽입)

마이그레이션 관리 팁

변경 사항마다 마이그레이션 파일을 만들고, 커밋할 때 같이 올린다.
팀원은 pull 받은 후 npx prisma migrate dev로 DB 구조를 최신화한다.
불필요하게 마이그레이션을 여러 번 만드는 것보단, 관련 변경은 묶어서 관리한다.
운영 DB에서는 반드시 백업 후 적용한다.

마무리

데이터베이스 마이그레이션은 단순한 기술 용어를 넘어, 프로젝트의 안정성과 팀 협업의 효율을 지키는 필수 습관이다.

특히 여러 명이 동시에 개발하는 환경에서는 “누가, 언제, 무엇을 변경했는지”를 명확히 기록하는 것이 곧 품질 관리다.

처음에는 조금 번거롭게 느껴질 수 있지만, 마이그레이션을 꾸준히 사용하면 DB 구조 변경이 두렵지 않고, 버전 관리와 롤백까지 자유롭게 할 수 있다.

“코드는 Git이, DB는 마이그레이션이 관리한다” 이 원칙만 기억해도 프로젝트의 안정성은 한층 올라갈 것이다.

최근 글