(Spring Boot) flyway 데이터 마이그레이션 설정 방법

Flyway

Flyway란?

일반적으로 프로그램의 소스코드를 효과적으로 관리할 수 있게 해주는 형상 관리 도구(Configuration Management Tool)로 Git을 많이 사용하고 있는데요.

Flyway는 데이터베이스의 형상 관리를 목적으로 하는 오픈소스 데이터베이스 마이그레이션 툴입니다.

* 형상관리(Software Configuration Management) - 소프트웨어의 변경사항을 체계적으로 추적하고 통제하는 것

 

데이터베이스의 형상 관리를 통해 얻을 수 있는 이점으로는 크게 '데이터베이스 schema의 변경 이력이 남는다'는 것과 '데이터베이스 변경 작업을 안전하게 할 수 있다'는 것이 있는데요.

데이터베이스에서 어떤 문제가 발견되었을 때, 이전에 해당 DB를 수정한 이력이 남아있다면 그 내용을 통해 문제의 원인을 파악하거나 유추해볼 수 있는 등, 문제를 해결하는데 도움이 될 수 있습니다.

또한 코드를 통해 DB schema를 변경함으로써 변경 중에 발생할 수 있는 작업자의 실수(Human Error)가 줄어드는 장점이 있는데요. 배포 시에 schema를 변경하는 자동화도 가능합니다.

 

그러면 이어지는 내용을 통해 스프링 부트에서 Flyway를 적용하는 방법을 살펴보겠습니다.

 

/*

flyway는 다양한 방법으로 실행될 수 있는데요. 빌드 툴인 gradle, maven을 통해 실행하는 방법도 있지만 Spring Boot에서는 데이터베이스 마이그레이션 도구인 Flyway 및 Liquibase를 지원하기 때문에 Flyway를 보다 쉽게 적용할 수 있습니다.

*/

 

 

Spring Boot 프로젝트 Flyway 적용

 

1. 의존성 추가

<!-- https://mvnrepository.com/artifact/org.flywaydb/flyway-core -->
<dependency>
   <groupId>org.flywaydb</groupId>
   <artifactId>flyway-core</artifactId>
</dependency>

(maven dependency)

 

 

---

 

2. application.yml

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/flyway_test?serverTimezone=UTC&characterEncoding=UTF-8
    username: 
    password: 
  jpa:
    database-platform: org.hibernate.dialect.MySQL8Dialect
    show-sql: true
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        format_sql: true
  flyway:
    enabled: true
    baseline-on-migrate: true
    locations: classpath:/db/migration
    baseline-version: 1

(application.yml)

 

• spring.jpa.hibernate.ddl-auto: validate 

DB 초기화 전략에 사용되는 옵션 값은 validate를 사용했는데요. validate는 Entity와 테이블의 적합성이 맞는지 검증하고, 맞지 않은 경우 오류를 발생시킵니다.

 

 

• spring.flyway.enabled: true

해당 설정은 기본 값이 true이지만 직관적으로 명시할 수 있도록 추가하였습니다.

 

 

• spring.flyway.baseline-on-migrate: true

히스토리 테이블인 flyway_schema_history가 생성되어 있는 경우 false로 설정하며, true로 설정하면 히스토리 테이블이 없을 경우에 생성이 됩니다. default 값은 false입니다.

 

 

resources/db/migration

• spring.flyway.locations: classpath:/db/migration

default 위치는 main/resources/db/migration이며, 즉 resources 패키지에 db/migration 패키지를 만들고 해당 패키지 안에 스크립트 파일을 추가하면 됩니다. 물론 해당 설정을 통해 flyway 적용을 원하는 커스텀 패키지로 설정할 수도 있습니다.

 

 

• spring.flyway.baseline-version: 1

히스토리 테이블이 없을 경우 히스토리 테이블을 생성하면서 baseline 정보가 입력되는데 그때 시작되는 버전 정보입니다.

(히스토리 테이블이 없는 상태에서 baseline-version 옵션 값을 1로 지정했을 때, Flyway Baseline으로 인해 V1이 반영되지 않기 때문에 0으로 설정해야 한다는 내용이 있던데, 현재 테스트 결과 옵션 값이 1이더라도 V1이 정상적으로 적용되고 있어 해당 부분은 확인 중입니다.)

 

 

---

 

3. 스크립트 생성 네이밍 규칙

스크립트 파일 네이밍 규칙

(출처 : https://flywaydb.org/documentation/concepts/migrations#naming)

 

• Prefix

Prefix에는 V(Versioned), U(Undo), R(Repeatable)의 3가지 종류가 있는데요.

V는 현재 버전을 새로운 버전으로 업데이트하는 경우, U는 현재 버전을 이전 버전으로 되돌리는 경우, R은 버전에 관계없이 매번 실행하는 경우에 사용됩니다.

 

• Version

V와 U는 버전이 명시되어야 하며, R은 버전이 명시되지 않아도 상관이 없는데요.

 

Flyway의 핵심 기능인 Versioned Migrations는 마이그레이션 스크립트의 최신 버전과 현재 데이터베이스의 schema 버전을 비교하여 차이점이 있다면 마이그레이션 스크립트를 순차적으로 실행하여 최신 schema와의 격차를 좁혀나가는 방법입니다.

때문에 마이그레이션 스크립트를 추가할 때는 항상 최신 마이그레이션 스크립트보다 큰 숫자로 버전을 설정해야 하며, 이때 사용되는 버전은 단순하게 1, 2, 3으로 나타낼 수 있도 있지만 20221204와 같은 날짜로도 명시할 수 있습니다.

 

• Separator

__ (언더바 2개)로 작성되어야 한다는 규칙이 있습니다.

 

• Description

스크립트의 내용에 맞게 자유롭게 적을 수 있으며, 단어의 구분은 _ (언더바 1개)로 하게 됩니다.

 

 

---

 

4. flyway 사용 시 주의할 점

출처: docs.spring.io

Spring Boot는 기본적으로 schema.sql과 data.sql을 통해 데이터베이스 스키마를 초기화하고 데이터를 추가할 수 있는 기능을 제공하는데요. 하지만 이 기능을 사용할 때 Flyway와 함께 사용해서는 안된다는 주의점이 있습니다.

 

 

 

< 참고 자료 >

https://backtony.github.io/spring/2021-10-22-spring-db-1/

https://tecoble.techcourse.co.kr/post/2021-10-23-flyway/

https://hudi.blog/dallog-flyway/