Skip to content

DB Migration

wcorn edited this page Apr 5, 2026 · 1 revision

DB 마이그레이션 전략

Liquibase를 사용한 스키마 버전 관리 및 배포 전략.

1. 기본 방침

환경 DDL 관리 방식 이유
prod Liquibase 변경 이력·롤백·재현성 보장
local Hibernate ddl-auto: update 빠른 프로토타이핑, 개발 생산성
test Hibernate ddl-auto: create-drop 테스트 격리 (TestContainers)

prod만 Liquibase로 엄격 관리. 로컬 개발 편의성을 위해 개발 단계는 Hibernate 자동 관리.

2. 파일 구조

be/orino-app-api/src/main/resources/db/changelog/
├── db.changelog-master.yaml          # 마스터 (include 순서 관리)
└── changes/
    ├── 001-create-member.yaml
    ├── 002-create-category.yaml
    ├── ...
    └── 014-create-indexes.yaml

파일명 규칙: {순번 3자리}-{동작}-{대상}.yaml

  • 순번: 단조 증가 3자리
  • 동작: create, add, alter, drop, rename
  • 대상: 테이블·컬럼·인덱스명

3. ChangeSet 작성 규칙

3.1 기본 포맷

databaseChangeLog:
  - changeSet:
      id: 001-1
      author: wcorn
      changes:
        - createTable:
            tableName: member
            columns:
              - column: {name: id, type: BIGINT, autoIncrement: true, constraints: {primaryKey: true}}
              - column: {name: login_id, type: VARCHAR(50), constraints: {nullable: false, unique: true}}

3.2 id 네이밍

  • 한 파일당 여러 changeSet: 001-1, 001-2 …
  • 파일 순번과 일치시켜 추적 용이

3.3 author

  • 모두 wcorn 통일

3.4 금지 사항

  • 이미 배포된 changeSet 수정 금지: Liquibase가 DATABASECHANGELOG 테이블의 checksum으로 검증. 수정 시 배포 실패
  • id 재사용 금지: 파일 삭제 후 동일 id 사용 불가
  • include 순서 변경 금지: 마스터 파일의 include 순서가 실행 순서

4. 작업 유형별 가이드

4.1 테이블 추가

새 엔티티 추가 시.

# changes/015-create-new-entity.yaml
databaseChangeLog:
  - changeSet:
      id: 015-1
      author: wcorn
      changes:
        - createTable:
            tableName: new_entity
            columns:
              - column: {name: id, type: BIGINT, autoIncrement: true, constraints: {primaryKey: true}}
              - column: {name: member_id, type: BIGINT, constraints: {nullable: false}}
              - column: {name: created_at, type: DATETIME, constraints: {nullable: false}}
              - column: {name: updated_at, type: DATETIME, constraints: {nullable: false}}
        - addForeignKeyConstraint:
            baseTableName: new_entity
            baseColumnNames: member_id
            constraintName: fk_new_entity_member
            referencedTableName: member
            referencedColumnNames: id

4.2 컬럼 추가

- changeSet:
    id: 016-1
    author: wcorn
    changes:
      - addColumn:
          tableName: goal
          columns:
            - column: {name: expected_completion_date, type: DATE}

기본값 있는 NOT NULL 컬럼 추가 (기존 데이터 존재 시):

- addColumn:
    tableName: goal
    columns:
      - column:
          name: pace_status
          type: VARCHAR(20)
          defaultValue: "ON_TRACK"
          constraints: {nullable: false}

4.3 컬럼 변경

기존 컬럼 타입 변경은 데이터 손실 위험. "확장 → 마이그레이션 → 축소" 3단계 분할:

  1. 확장: 새 컬럼 추가 (NULL 허용)
  2. 마이그레이션: 애플리케이션에서 양쪽 쓰기 → 기존 데이터 변환 → 읽기 전환
  3. 축소: 기존 컬럼 제거

한 릴리즈에 몰아 하지 않는다.

4.4 인덱스 추가

온라인 인덱스 추가 (MySQL 8+ 기본 지원).

- createIndex:
    tableName: block
    indexName: idx_block_date_member
    columns:
      - column: {name: block_date}
      - column: {name: member_id}

대용량 테이블은 생성 중 서비스 영향 측정.

4.5 데이터 변경 (DML)

스키마와 함께 필요한 초기 데이터.

- changeSet:
    id: 017-1
    author: wcorn
    changes:
      - insert:
          tableName: priority_rule
          columns:
            - column: {name: rule_type, value: "OVERDUE_REVIEW"}
            - column: {name: priority, valueNumeric: 1}

복잡한 데이터 변환은 별도 배치 또는 관리 스크립트 권장.

5. 배포 흐름

코드 작성 → Liquibase changeSet 추가 → local에서 Entity 검증
    │
    ▼
ddl-auto: validate가 prod에서 schema 일치 확인
    │
    ▼
PR 머지 → CD → 새 BE 이미지 배포
    │
    ▼
BE Pod 시작 시 Liquibase가 미적용 changeSet 실행
    │
    ▼
DATABASECHANGELOG 테이블에 실행 이력 기록

주의: ddl-auto: validate이므로 Entity와 실제 스키마가 불일치하면 애플리케이션 시작 실패. Liquibase changeSet 없이 Entity만 변경하면 배포 실패한다.

6. 롤백 전략

Liquibase의 rollback 태그로 역방향 변경 정의 가능.

- changeSet:
    id: 015-1
    author: wcorn
    changes:
      - createTable: {...}
    rollback:
      - dropTable:
          tableName: new_entity

현실적 방침:

  • 단순 변경 (createTable, addColumn): rollback 작성
  • 복잡한 변경 (데이터 이관): rollback보다 forward fix(새 changeSet으로 복구)
  • prod 긴급 롤백: 데이터 손실 시 백업 복원이 더 안전 (Backup-Recovery §5)

7. 로컬 개발 ↔ prod 차이 대응

로컬은 ddl-auto: update로 Entity 변경이 자동 반영되지만, prod는 Liquibase changeSet이 있어야만 반영된다.

Entity 변경 시 체크리스트:

  • Entity 클래스 수정
  • 대응하는 Liquibase changeSet 추가 (changes/ 하위)
  • db.changelog-master.yaml에 include 추가
  • 로컬에서 spring.liquibase.enabled=true로 임시 전환 → 실제 적용 확인
  • 테스트 코드에서 Entity 변경 반영 확인

8. 초기 세팅 (참조)

신규 환경 구축 시.

1. MySQL 빈 DB 생성 (DB명: orino)
2. BE 애플리케이션 실행
3. Liquibase가 모든 changeSet 순차 적용
4. DATABASECHANGELOG, DATABASECHANGELOGLOCK 테이블 자동 생성

9. 관련 문서

Clone this wiki locally