콘텐츠로 이동

DB 마이그레이션 (Flyway)

Flyway로 스키마 버전 관리. Spring Boot 시작 시 자동 마이그레이션. flyway_schema_history 테이블로 적용 이력 추적.

1. 파일 네이밍

V{버전}__{설명}.sql        # __ 2개로 구분, 설명은 snake_case
용도 버전 범위 예
스키마 변경 V1 ~ V999 V2__add_phone_number.sql
시드 데이터 V1000 ~ V1000__local_seed.sql

디렉토리: src/main/resources/db/migration/(공통) + db/seed/{local,dev}/(환경별 시드).

2. 환경별 locations / 검증

환경 locations CD 검증 실패 시
Local migration + seed/local — —
Dev (develop 머지) migration + seed/dev flywayInfo 배포 계속 (|| true)
Prod (main 머지) migration (시드 없음) flywayValidate 배포 중단

flywayValidate: 체크섬 일치·파일 존재·버전 순서 정합성 검증.

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true   # 기존 DB에 history 없으면 version=0 baseline 생성
    baseline-version: 0

⚠️ PROD 서버는 Hibernate ddl-auto: none. main 머지 후 DDL이 Flyway로 적용되도록 보장(또는 직접 실행 필요) → teams/engineering/infra/environments.

3. 새 마이그레이션 흐름 (V2 예)

  1. V2__*.sql 작성 → 2. Local 테스트(./gradlew bootRun) → 3. PR → develop 머지(Dev 자동 적용) → 4. Dev 검증 → 5. main 머지(Prod flywayValidate 통과 후 적용)

4. 작성 가이드

  • 한 마이그레이션 = 한 목적
  • Flyway 기본 롤백 미지원 → 신중히. 되돌릴 땐 새 마이그레이션(V3__rollback_...)
  • 가능하면 IF NOT EXISTS (멱등), 변경 목적 주석
  • 이미 적용된 파일은 절대 수정 금지 (체크섬 불일치 → validate 실패)
  • 같은 버전 번호 중복 금지(팀 충돌)

5. 문제 해결

  • 실패: 로그 확인 → DELETE FROM flyway_schema_history WHERE success=0; → SQL 수정 후 재실행
  • 체크섬 불일치: 권장은 새 마이그레이션. 비상시만 history checksum 수동 업데이트

6. 관련