[Spring] Flyway DB 스키마 관리

Spring Boot 프로젝트에서 DB 스키마를 안정적으로 관리하려면
개발 환경 / 운영 환경 / 로컬 환경에서 모두 동일한 테이블 구조를 유지할 수 있어야 한다.
이때 가장 많이 사용하는 방법이 Flyway 기반 데이터베이스 마이그레이션이다.

 

프로젝트에서도 Flyway를 적용해서
DB 구조 변경을 코드로 관리하고, 버전 충돌 없이 배포할 수 있는 구조를 만들었다.

---

1. Flyway란 무엇인가?

Flyway는 데이터베이스 스키마를 버전 관리하는 도구다.

• 테이블 생성
• 컬럼 추가/삭제
• 인덱스 생성
• 제약조건 수정
• 초기 데이터 삽입(Seed)

이 모든 DB 작업을 **SQL 파일로 버전 관리(V1, V2, V3...)**하고
Spring Boot 애플리케이션 실행 시 자동으로 적용한다.

즉,

“로컬 · 개발 · 운영 DB 스키마를 모두 동일하게 유지할 수 있는 시스템”

이라고 보면 된다.

---

2. 의존성 추가

Gradle 기준:

 

implementation("org.flywaydb:flyway-core")
implementation("org.flywaydb:flyway-mysql") // DB 엔진에 맞게 사용

---

3. Flyway 기본 설정 (application.yml)

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true
    locations: classpath:db/migration

✔ 옵션 설명

옵션	설명
enabled	Flyway 활성화
baseline-on-migrate	기존 DB가 이미 테이블을 가지고 있어도 마이그레이션 진행
locations	SQL 파일 위치

기본 경로

src/main/resources/db/migration

여기에 SQL 파일을 넣으면 Flyway가 자동으로 실행된다.

---

4. 마이그레이션 파일 네이밍 규칙 (중요!)

Flyway는 파일명을 기준으로 실행 순서를 정한다.

 

V1__init.sql
V2__add_user_table.sql
V3__add_place_table.sql
V4__modify_post_table.sql

규칙은 다음과 같다:

• V숫자__설명.sql
• 언더바 2개(__) 반드시 포함
• 숫자 순서대로 실행

예시:

 

-- V1__init.sql
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    email VARCHAR(255) NOT NULL,
    password VARCHAR(255) NOT NULL
);

---

5. Flyway 동작 방식

애플리케이션 실행 → Flyway 자동 동작

1. flyway_schema_history 테이블 확인
2. 아직 적용되지 않은 마이그레이션 파일 탐색
3. 새로운 V 파일을 순서대로 실행
4. 실행 이력을 flyway 테이블에 기록

DB 내부에는 Flyway의 이력 테이블이 자동 생성된다:

이 덕분에 같은 마이그레이션이 중복 실행되지 않는다.

---

6. 활용 예시

✔ 테이블 생성

 

V1__create_member_table.sql  
V2__create_post_table.sql  
V3__create_place_table.sql  
V4__create_reservation_table.sql  
...

✔ 컬럼 추가

 

-- V8__add_review_summary_column.sql
ALTER TABLE reviews
ADD COLUMN summary TEXT;

✔ 인덱스 추가

 

-- V9__add_index_on_reservation_status.sql
CREATE INDEX idx_reservation_status
ON reservations (status);

✔ 초기 데이터 삽입(Seed)

 

-- V10__insert_default_categories.sql
INSERT INTO categories(name) VALUES ('캠핑'), ('등산'), ('스포츠');

---

7. Flyway를 사용하면 좋은 점

1) DB 스키마 버전 관리

누가 언제 어떤 테이블을 변경했는지 기록됨.

2) 운영/개발/로컬 환경 간 불일치 제거

모든 환경에서 동일한 SQL이 차례대로 실행됨.

3) 배포 자동화

Spring Boot 실행만 하면 DB가 자동 업데이트됨.

4) Git으로 DB 스키마도 협업 관리

모든 테이블 변경이 PR로 관리됨 → “누가 마음대로 ALTER TABLE 하지 못함”

5) Rollback도 간단

문제 생기면 해당 버전 SQL만 되돌리면 됨.

---

8. 실서비스 적용 시 팁

✔ 1) 마이그레이션 파일은 절대 수정 금지

한번 배포된 V 파일을 수정하면 Flyway가 “변조됨”으로 인식하고 에러 발생.

잘못 만들었으면:

• V11__wrong.sql → 삭제 ❌
• V12__fix_wrong.sql → 새로 추가 ⭕

이 방식으로 해결해야 한다.

---

✔ 2) 운영 DB에 직접 ALTER TABLE 금지

사람이 직접 쓴 ALTER TABLE은 추후 Flyway와 충돌함.

마이그레이션 파일로 관리하는 것이 원칙.

---

✔ 3) 대용량 환경에서는 DDL 작업에 주의

• 컬럼 추가는 거의 즉시 되지만
• 테이블 구조 변경은 테이블 락(lock)이 생길 수 있음
• Flyway는 실행 순서를 보장하지만 DB 락까지 해결해주지는 않음

---

9. 마무리

“데이터베이스 스키마를 코드처럼 버전 관리해주는 도구”

Flyway를 적용한 뒤:

• 스키마 변경 이력 관리가 명확해졌고
• 배포 후 테이블 불일치 오류가 사라졌으며
• 팀 단위 개발에서도 DB 변경을 안전하게 공유할 수 있었다.

Spring Boot 프로젝트에서는 사실상 필수 도구이기 때문에
새로 시작하는 프로젝트에서도 Flyway는 기본으로 넣는 것이 좋다.