[SpringBoot] Flyway로 DB 마이그레이션 및 DDL 작성

SpringBoot와 Oracle, MyBatis를 이용하여 재고/물품 관리 시스템을 개발하던 중, DDL 스크립트를 저장하고 관리할 필요성을 느끼게 되었다

특히 MyBatis는 SQL 실행 도구로 스키마를 자동 생성해주지 않기 때문에, 테이블 생성 시 DDL 스크립트를 필수로 작성해야 함 --> Flyway가 필수적

❗JPA 사용 시에도 Flyway를 사용한다
JPA 사용 시 Hibernate가 테이블 생성 및 수정을 자동으로 해주기 때문에 Flyway가 필요 없다고 생각할 수 있으나, Flyway 없이 `ddl-auto` 기능만을 사용하면 테이블 변경 시 누가 언제 어떤 컬럼을 추가했는지 추적 불가함
따라서 실수를 방지하고 sql 버전 관리를 위해 JPA + Flyway 조합도 많이 사용함

 

📌 Flyway

DB 마이그레이션 버전 관리 도구

코드를 Git으로 버전 관리하듯이, DB 스키마 변경 이력도 파일로 관리할 수 있게 해줌

Flyway가 실행한 이력은 FLYWAY_SCHEMA_HISTORY 테이블에 자동으로 기록됨

• 각 SQL 파일에 버전 번호를 붙임 --> Flyway가 아직 실행되지 않은 파일만 골라서 순서대로 자동 실행

 

마이그레이션 파일명 규칙

Prefix + Version 번호 + __(언더바 2개) + 설명 + 확장자 ==> V<번호>__설명.sql

• prefix: V(버전 마이그레이션), R(반복 마이그레이션), U(취소 마이그레이션 - 유료)
• version: 버전 마이그레이션에서만 사용됨. 숫자, 점(.), 언더바(_) 조합
  • V2, V2.1, V2_1
• separator: 버전과 설명을 구분하는 구분자. 언더바 2개 사용 (__)
• description: schema_version 테이블에 저장시 설명 컬럼에 저장됨
• suffix: 확장자 기본은 .sql

 

DDL 관리 방법 비교

방법	도구	특징
DDL 직접 실행	sqlplus / DBeaver	가장 직접적, but 이력이 남지 않음
schema.sql 자동 실행	SpringBoot 내장	앱 기동 시 SQL 파일 자동 실행 --> 매번 DROP, CREATE 필요
Flyway	마이그레이션 툴	버전 관리 가능

 

📌 프로젝트

구조

src/main/resources/
├── db/
│   └── migration/
│       ├── V1__create_sequences.sql      ← Sequence 생성
│       ├── V2__create_tables.sql         ← 테이블 + 컬럼 COMMENT 생성
│       ├── V3__create_trigger.sql        ← 트리거 생성
│       └── V4__insert_sample_data.sql    ← 샘플 데이터
├── mapper/
│   └── item/
└── application.yml

 

설정 방법

build.gradle 의존성 추가

// Flyway
implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-database-oracle'  // Oracle 전용

application.yml 설정

oracle: sqlplus: true 설정이 없으면 V3의 트리거(PL/SQL 블록) 실행 시 에러 발생

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration   # SQL 파일 위치
    baseline-on-migrate: true           # 기존 테이블이 있어도 에러 안 남
    oracle:
      sqlplus: true                     # PL/SQL 블록(BEGIN~END) 실행 허용

 

SQL 파일 목록

• V1__create_sequences.sql
  • 각 테이블의 PK용 시퀀스 생성 파일
  • Oracle은 AUTO\_INCREMENT 대신 Sequence로 PK를 생성함
• V2__create_tables.sql
  • 테이블 + 각 테이블/컬럼 COMMENT 작성
• V3__create_trigger.sql
  • 1:1 관계인 두 테이블 A, B가 있을 때, A테이블에서 데이터가 삽입된 경우 B 테이블에 자동으로 관련 행이 생성되도록 트리거 작성
  • 데이터 무결성 보장 위함
• V4__insert_sample_data.sql
  • 테스트용 샘플 데이터 입력

 

📌 앱 실행 시 동작 흐름

앱 실행
  └─ Flyway 활성화
       └─ FLYWAY_SCHEMA_HISTORY 테이블 확인 (없으면 자동 생성)
            └─ db/migration/ 폴더 스캔
                 └─ 미실행 파일만 순서대로 Oracle에 자동 실행
                      └─ 실행 이력 기록

 

정상 실행 로그 예시

Flyway Community Edition - Flyway by Redgate
Database: jdbc:oracle:thin:@localhost:1521/XEPDB1 (Oracle 21.0)
Successfully validated 4 migrations (execution time 00:00.025s)
Migrating schema to version 1 - create sequences
Migrating schema to version 2 - create tables
Migrating schema to version 3 - create trigger
Migrating schema to version 4 - insert sample data
Successfully applied 4 migrations (execution time 00:02.503s)

 

확인 쿼리

-- Flyway 실행 이력 확인
SELECT version, description, success, installed_on
FROM flyway_schema_history
ORDER BY installed_rank;

-- 샘플 데이터 + 트리거 동작 확인
-- 이 부분은 각자 작성한 테이블 정보에 맞게 작성
SELECT i.item_name, i.item_code, s.current_qty
FROM item i JOIN stock s ON i.item_id = s.item_id;

 

💡 나중에 스키마를 변경해야 할 때

기존 파일은 절대 수정하지 않고 새 버전 파일 추가

이미 실행된 파일을 수정하면 Flyway가 체크섬 불일치 에러를 냄

V5__add_column_item.sql       ← 컬럼 추가
V6__create_index.sql          ← 인덱스 추가

💡 DB 초기화가 필요할 때

# 컨테이너 + 데이터 볼륨 모두 삭제 후 재시작
docker compose down -v
docker compose up -d

# 이후 앱 재실행 → Flyway가 V1~V4 처음부터 다시 실행

 

---

참고

https://velog.io/@hyun-jii/Flyway-%EC%A0%95%EC%9D%98-DB-%EB%A7%88%EC%9D%B4%EA%B7%B8%EB%A0%88%EC%9D%B4%EC%85%98-%EB%8F%84%EA%B5%AC

Flyway 정의, DB 마이그레이션 도구

https://hu-bris.tistory.com/243

유용한 DB 마이그레이션 도구, Flyway