DB 마이그레이션

DB 마이그레이션 적용

프로젝트를 진행하다 보면 데이터베이스 구조가 처음 그대로 유지되는 경우는 거의 없습니다.
새로운 기능이 생기면 컬럼이 추가되고, 인덱스가 바뀌고, 테이블이 나누어집니다.

 

마찬가지로 저희도 프로젝트 초기에 설계한 데이터베이스 구조가 바뀌어서 버전관리를 하면 좋겠다는 생각을 했습니다.
누가 언제, 왜 변경했는가를 추적할 수 없다면 운영 환경에서는 큰 리스크가 발생할 것이 분명합니다.

이런 리스크 문제를 해결하는 방법이 바로 DB 마이그레이션입니다.

 

이번 글에서는 DB마이그레이션 개념과 프로젝트에 어떤 마이그레이션 방법을 왜 적용했는지 정리해보겠습니다.

그리고 DB 마이그레이션 방식에서 기존 방식으로 변경했던 이유까지 적어보려 합니다.

 

---

 

1. DB 마이그레이션이란?

우선 DB 마이그레이션은
시간이 지남에 따라 데이터베이스 스키마(테이블, 컬럼, 인덱스, 제약조건 등) 가 변경될 때
그 변화를 안전하게 버전별로 관리하고 환경(로컬/운영) 간 일관되게 적용하는 절차입니다.

 

쉽게 말해 데이터베이스의 Git 버전 관리라고 생각하면 됩니다.

 

예시로 살펴보기

버전 변경	내용	설명
V1	tests 테이블 생성	초기 테이블 구조 정의
V2	web_vitals 테이블 추가	성능 지표 테이블 추가
V3	scores 컬럼 추가	총점 컬럼 추가
V4	scores에 UNIQUE 인덱스 추가	중복 방지 및 성능 개선

이러한 변경을 Flyway나 Liquibase 같은 툴이 V1, V2, V3... 버전 단위로 추적하며
모든 환경에서 동일한 순서로 DB를 진화시킵니다.

 

이러한 DB 마이그레이션 방식 모두 테이블에 실행 내역을 기록하고

개발자 간 스키마 변경 이력 공유, 배포 자동화, 운영환경 무중단 업데이트를 할 수 있다는 장점이 있습니다. 

 

이 두 방식의 제일 큰 차이점은 파일 형식에 있을 것 같습니다.

Flyway는 주로 SQL 파일 (V1__init.sql, V2__add_table.sql)로 이루어져있고
Liquibase는 XML, YAML, JSON, SQL 등 다양합니다.

 

저는 Flyway가 Spring boot와 통합이 잘 되어있고

SQL 위주라 러닝커브가 더 낮다고 판단해 도입하게 되었습니다.

 

---

 

2. 스키마 작성 방식

스키마(Schema)는 DB 구조의 정답 상태를 정의하는 SQL 문서입니다.

즉 애플리케이션 코드로 DB 구조를 설계하는 것입니다.

이를 관리하는 방식에는 두 가지 철학이 있습니다.

접근 방식	설명	장점	단점
마이그레이션 방식	변경 내역을 V1, V2, V3 식으로 누적 관리	변경 이력 추적 가능 팀 협업 안정	복잡해짐, 롤백 어려움
단일 스키마 방식 (현재 로컬용)	항상 최신 스키마(schema.sql)만 유지	단순, 복구 쉬움	변경 이력 추적 불가

 

작성 원칙

1. 명시적 제약조건
    PK, FK, UNIQUE, INDEX는 반드시 정의합니다.

CREATE TABLE web_vitals ( id uuid PRIMARY KEY, test_id uuid NOT NULL UNIQUE REFERENCES tests(id) ); 
CREATE INDEX IF NOT EXISTS idx_web_vitals_test_id ON web_vitals(test_id);

2. DDL 순서 주의
    외래키(FK)는 참조 대상이 먼저 존재해야 하므로 부모 → 자식 순서로 테이블을 생성합니다.

3. IF NOT EXISTS / CASCADE 신중히 사용
    개발 환경에서는 편리하지만, 운영 환경에서는 데이터 유실 위험이 있습니다.

4. id는 UUID, 시간은 timestamptz(UTC)
    일관된 규칙을 유지해야 ORM과의 매핑도 쉬워집니다.

 

---

 

3. 환경별 적용 방식

지금 진행중인 프로젝트에서도 개발환경과 운영환경을 마이그레이션 방법을 구분해서 사용하려 했습니다.

우선 개발 환경에서는 Flyway를 도입해서 사용했지만

백엔드 개발을 처음하는 팀원이 많아 이전 버전 파일 코드를 수정하는 등 실수가 잦았습니다.

 

그래서 개발 환경에서는 schema.sql을 적용하고 운영 환경에서 다시 flyway를 도입하려고 합니다.

 

a) 개발 환경(Local / Docker Compose)

개발 환경에서는 빠른 초기화와 실험이 중요하기 때문에
그리고 팀원이 실수하는 것을 방지하고자
schema.sql 혹은 data.sql을 자동 적용하는 구조를 사용했습니다.

spring:
  sql:
    init:
      mode: always
      schema-locations: classpath:db/schema.sql

 

 

로컬 DB는 개발 환경이므로 스키마를 덮어써도 무방하도록 schema.sql 스키마를 사용했습니다.

물론 deltas 폴더에서 변경된 코드를 기록하며 히스토리도 관리했습니다.

 

b) 운영 환경(Production)

운영 DB에서는 절대 schema.sql을 자동 실행하지 않도록 해야 합니다.

이유는 다음과 같습니다.

1. 데이터 유실 위험
   DROP TABLE이나 CREATE TABLE이 실행되면 데이터가 삭제될 수 있습니다.
2. 데이터 변환이 필요함
   컬럼 이름, 타입, 인덱스 등을 변경할 때 기존 데이터도 변환해야 합니다.
3. 자동 실행은 예측 불가능
   앱이 재기동될 때마다 schema.sql이 실행되면, 운영 DB를 덮어쓸 수 있습니다.

해결 방법

그래서 운영 환경에서는 Flyway/Liquibase를 사용합니다.

• Flyway는 DB 내부에 flyway_schema_history 테이블을 만들어
  현재 DB가 몇 번째 버전까지 적용되었는지를 추적합니다.
• 애플리케이션이 기동될 때 Flyway가 자동으로 버전 비교 → 필요 시 ALTER 실행

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration

 

 

---

 

 

4. 스키마 관리 시 주의사항

항목	설명
DROP TABLE 사용 자제	운영 데이터가 삭제될 수 있음
FOREIGN KEY CASCADE 주의	연쇄 삭제 위험 → 명시적 삭제 권장
schema.sql 환경 분리	로컬: always, 운영: never
DDL ↔ 코드 싱크 맞추기	JPA 엔티티 변경 시 ddl-auto=validate로 검증
UNIQUE INDEX vs CONSTRAINT 구분	무결성 vs 성능 목적에 맞게 선택
UTC + timestamptz 통일	시간대 일관성 유지
백업 루틴 필수	실수 시 pg_dump로 복원 가능

 

---

 

5. 핵심 정리

• DB 마이그레이션은 데이터베이스 구조를 시간의 흐름에 따라 안전하게 진화시키는 방법입니다.
• 개발 환경에서는 schema.sql을 사용해 빠르게 초기화하고
  운영 환경에서는 Flyway나 Liquibase로 버전별 변경을 관리해야 합니다.
• 특히 클라우드(RDS)에서는 schema.sql 자동 실행을 반드시 꺼야 합니다.
• 모든 변경은 명시적 마이그레이션 파일을 통해 적용해야 안전합니다.