Flyway - ? (PostgreSQL)

🐣 상황

MSA 환경에서 여러 DB 테이블을 만들고, 공유하고, 수정하고, 버전 관리를 하다 보면 이런 상황이 발생한다.

• "이 테이블 필드 추가한거 DB에 반영했어?"
• "어제 로컬에서 되던거 dev 서버에선 왜 오류나지?"
• "운영 DB에서 column 빠져서 장애 났어..."

👉 DDL, DML 모두 코드처럼 관리할 수는 없을까?

✨ Flyway란?

DB 스키마 및 초기 데이터를 버전별로 관리해주는 마이그레이션 도구

Spring Boot와는 거의 자동 통합되어 있으며, src/main/resources/db/migration 디렉터리 아래 SQL 파일을 넣으면 자동 실행된다.

📦 왜 Flyway를 써야 할까?

✅ 1. DB도 "버전 관리"가 필요하다

• Git으로 코드 히스토리를 관리하듯,
• DB도 버전별로 관리해야 협업과 배포가 안정적이다.

✅ 2. 환경 간 스키마 불일치 방지

• local, dev, staging, prod 등 환경이 많아질수록 스키마 싱크가 깨진다
• Flyway는 실행된 마이그레이션 기록(flyway_schema_history)을 저장해서 중복 실행을 방지하고 동일한 DB 상태를 보장

✅ 3. 애플리케이션 실행 시 자동 마이그레이션

• Spring Boot 앱이 실행될 때 Flyway가 DB 상태를 검사하고, 필요한 SQL만 자동 실행
• 운영 배포 시에도 INSERT, ALTER가 코드 배포와 함께 자동 처리됨

✅ 4. SQL 기반이라 명시적이고 검증 가능

• JPA ddl-auto는 동적으로 테이블을 만들고 수정하지만, 명시적이지 않음
• Flyway는 정적인 SQL로 DB 변경 내역이 명확하게 남음
• 리뷰 가능 / rollback 가능 / 기록 가능

✅ 5. 운영 중에도 안정적인 DB 구조 진화

• 운영 DB에 테이블을 삭제하거나 컬럼을 수정할 때
• Flyway로 점진적 마이그레이션이 가능하다

📄 마이그레이션 기록 저장 위치: flyway_schema_history

Flyway는 마이그레이션을 실행하면, 해당 정보를 DB 내부 테이블에 기록으로 남깁니다.

• flyway_schema_history

이 테이블은 Flyway가 어떤 마이그레이션 파일을 언제 실행했는지 추적하기 위해 자동으로 생성되며, 주요 컬럼은 다음과 같습니다:

컬럼명	설명
installed_rank	실행 순서
version	마이그레이션 버전 (V1, V2, …)
description	__ 뒤에 있는 설명 (create_artist_table 등)
script	실행된 파일명 (V1__create_artist_table.sql)
installed_on	실행된 날짜/시간
success	성공 여부 (true / false)

---

✅ 예시

SELECT * FROM flyway_schema_history;

📌 Flyway 마이그레이션 파일명 규칙 (V1__ 명명법)

Flyway는 마이그레이션 파일 이름을 통해 버전 관리와 실행 순서를 자동으로 판단합니다. 파일명은 반드시 아래와 같은 규칙을 따라야 합니다

✅ 예시

파일명	의미
V1__create_artist_table.sql	버전 1, 아티스트 테이블 생성
V2__insert_admin_account.sql	버전 2, 어드민 계정 삽입
V3__add_column_to_album.sql	버전 3, 앨범 테이블에 컬럼 추가

---

✅ 규칙 요약

• V → 반드시 대문자 V로 시작
• {버전번호} → 정수 (1, 2, 3, …) 또는 점(.) 포함 가능 (1.1, 2.5)
• __ → 언더스코어 2개 (__)가 꼭 필요함
• {설명} → 마이그레이션 내용 요약 (단어는 _로 구분)
• 확장자 → .sql로 끝나야 함

---

🧠 실행 순서 주의

Flyway는 파일 이름 기준으로 정렬해서 실행하므로, 다음 순서가 됨:

V1...
V2...
V10... ✅
V11...

V1.1__..., V2.0__... 같은 소수점도 가능하지만, 보통은 정수 버전이 더 명확하고 협업에 좋음

---

❗️ 잘못된 예시 (실행되지 않거나 오류 발생)

잘못된 이름	이유
v1__init.sql	V는 반드시 대문자
V1_init.sql	언더스코어가 1개
V001-create.sql	__ 아닌 - 사용
V1__.sql	설명이 없음

---

✅ 권장하는 명명 규칙

V{버전번호}__{도메인}_{행위}.sql

예:

• V1__artist_create_table.sql
• V2__admin_insert_data.sql
• V3__album_add_sort_order_column.sql

🧠 JPA ddl-auto와의 차이점은?

항목	ddl-auto	Flyway
제어 방식	자동 생성/수정	SQL 파일로 명시
운영 환경 적합성	❌ 위험	✅ 안전
버전 관리	❌ 불가능	✅ 버전별 관리 가능
실행 시점	애플리케이션 실행 시 바로 반영	애플리케이션 실행 시, 버전 비교 후 필요한 SQL만 실행

🔧 설정 예시 (application.yml)

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true
    locations: classpath:db/migration
baseline-on-migrate: true → 기존 DB가 있어도 첫 마이그레이션부터 허용

💡 결론

📌 Flyway는 MSA 기반의 실서비스에서 DB를 신뢰 가능하고 안전하게 진화시킬 수 있는 필수 도구다.

• 개발 환경: local/dev/prod 환경 차이 제거
• 협업: 모든 스키마/데이터 변경 내역이 명시적으로 기록
• 운영: 배포 시점에 맞춰 자동 적용 → 장애 감소

"코드는 Git으로, DB는 Flyway로"