Flyway란?

Flyway 기초

정의
- DB 스키마를 Git처럼 버전 관리하고 배포 시 자동으로 마이그레이션해 주는 도구임
- 애플리케이션 코드와 DB 스키마의 변경 사항을 동기화하여 배포 안정성을 높임
필요성
- 수동으로 SQL을 실행하면 사람의 실수로 인해 누락되거나 순서가 꼬일 위험이 있음
- 개발, 스테이징, 운영 환경 간의 스키마 불일치 문제를 해결함

버전 관리 규칙
- 파일 이름에 버전을 명시하여 순서를 제어함
- V1__init.sql, V2__add_user_table.sql 형식을 따름 (V + 버전 + __ + 설명)
메타데이터 관리
- 데이터베이스 내부에 flyway_schema_history 테이블을 생성함
- 이미 실행된 스크립트의 버전, 체크섬(Checksum), 실행 일시를 기록함
마이그레이션 프로세스
- 애플리케이션 시작 시 DB에 연결함
- 메타데이터 테이블을 조회하여 아직 실행되지 않은 스크립트만 식별함
- 버전 순서대로 SQL을 실행하고 성공 시 메타데이터에 기록함
- 결과적으로 모든 환경이 동일한 순서로 변경 사항을 반영하게 됨

Spring Boot 통합
- flyway-core 의존성만 추가하면 별도 설정 없이 바로 사용 가능함
- src/main/resources/db/migration 경로에 SQL 파일을 두면 부트 실행 시 자동 감지함
트랜잭션 지원
- PostgreSQL, SQL Server 등 DDL 트랜잭션을 지원하는 DB에서는 스크립트 실행을 트랜잭션으로 묶음
- 마이그레이션 실패 시 자동으로 롤백되어 부분 반영되는 문제를 방지함
- 주의사항
  - MySQL은 DDL 실행 시 암시적 커밋(Implicit Commit)이 발생하여 롤백이 불가능함
  - 실패 시 수동 복구가 필요할 수 있음
SQL 우선 (SQL-first)
- 특정 DSL(Domain Specific Language)이 아닌 표준 SQL을 그대로 사용함
- DB 벤더 고유의 기능(파티셔닝, 특정 인덱스 옵션 등)을 제약 없이 활용 가능함

Flyway와 Liquibase

특징	Flyway (심플함)	Liquibase (강력함)
작성 언어	SQL (표준 SQL 그대로 사용)	XML, YAML, JSON (추상화된 포맷)
러닝 커브	매우 낮음 (SQL만 알면 됨)	높음 (전용 문법 익혀야 함)
DB 종속성	종속적 (MySQL 쿼리는 Oracle에서 안 돌 수 있음)	독립적 (XML로 짜면 각 DB에 맞는 SQL로 변환됨)
롤백(Undo)	유료 (Teams 에디션) 또는 수동 관리	무료 (Rollback 태그 지원)
추천 대상	SQL이 편한 백엔드 개발자, 빠른 개발	DBA 팀이 따로 있거나, 여러 종류 DB를 동시 지원해야 할 때

Flyway와 Hibernate ddl-auto

구분	Hibernate ddl-auto (개발용)	Flyway (배포용)
용도	로컬 개발, 프로토타이핑	개발, 테스트, 운영(Prod) 모든 환경
안전성	데이터가 날아가거나, 의도치 않게 컬럼이 바뀔 수 있으며 변경 이력이 남지 않음	변경 이력 추적 및 배포 안정성변경 이력이 철저히 남고, 실패 시 애플리케이션 구동을 멈춰서 사고를 방지함

경로
- src/main/resources/db/migration
파일명 규칙
- V{버전}__{설명}.sql (언더바 _가 두 개임)
  - V1__init_schema.sql (최초 테이블 생성)
  - V2__add_phone_number.sql (컬럼 추가)
- R__{설명}.sql (Repeatable Migration)
  - 파일의 체크섬이 변경될 때마다 반복적으로 실행됨
  - View, Stored Procedure, Function 관리에 적합함
주의사항
- 한 번 실행된 파일(V1)은 절대 수정하면 안 됨
- 내용을 고치고 싶으면 V3__update_V1.sql을 새로 만들어야 함 (수정 시 Checksum 에러 발생)

체크섬 불일치 (Checksum Mismatch)
- 원인
  - 이미 성공한 V1__init.sql 파일을 수정하고 재배포할 때 발생함
- 해결 방법
  - 수동으로 DB의 체크섬 기록을 업데이트하거나, 신규 버전(V2)을 생성하여 대응함
마이그레이션 실패 시 수동 조치
- 원인
  - 트랜잭션을 지원하지 않는 DB (MySQL 등)에서 실패한 경우
- 해결 방법
  - 메타데이터 테이블에서 해당 실패 열(Success = false)을 직접 삭제해야 재실행이 가능함

Case A (Flyway 추천)

Case B (Liquibase 추천)

상황
- “하나의 스키마 정의 파일로 MySQL과 Oracle에 동시에 배포해야 한다.”
- “무료 버전에서 완벽한 자동 롤백 기능이 필수다.”
이유
- XML/YAML로 추상화하여 DB 벤더 독립성을 챙길 수 있음

Case C (아무것도 안 씀)

상황
- “극초기 개인 프로젝트라 스키마가 하루에 100번 바뀐다.”
이유
- 이럴 땐 그냥 ddl-auto: create로 밀어버리는 게 속 편할 수 있음
- 단, 배포 전에는 반드시 Flyway로 전환해야 함

도입 시점
- 프로젝트 시작할 때 바로 넣어야 함
- 나중에 넣으려면 baseline 설정으로 고생할 수 있음
  - baseline-on-migrate: true 설정은 기존 DB 스키마를 V1로 간주하고 마이그레이션을 시작하게 함

Spring Boot 설정

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true # 기존 DB가 있어도 무시하고 히스토리 테이블 생성