Flyway

📌 Flyway란?

Flyway 는 데이터베이스 형상 관리 도구로, 데이터베이스 스키마의 변경사항을 추적 및 관리할 수 있도록 한다. Git이 소스 코드를 관리하는 것을 생각하면 된다.

가장 큰 장점은 SQL마저 버전 관리가 가능해진다는 점이다. 또한 flyway_schema_history 테이블에서 스키마 변경 이력을 확인할 수 있어 문제 추적 또한 쉬워진다. 다만 작성한 마이그레이션 파일은 수정이 불가능하며 롤백이 제한적이라는 단점이 있다.

📌 설정

먼저 flyway 의존성을 추가한다.

dependencies {
    implementation 'org.flywaydb:flyway-core'

    // 사용하는 DB에 따라 추가 의존성이 필요할 수 있음.
    implementation 'org.flywaydb:flyway-mysql'
}

application.yml 에서 flyway 관련 속성을 설정한다. 주요 옵션은 다음과 같다.

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/my_database?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8
    username: your_username
    password: your_password

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

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        format_sql: true

enabled: flyway 활성화 여부를 설정한다. 기본값은 true 이다.

location: 마이그레이션 파일이 위치한 경로를 설정한다. 기본값은 classpath:db/migration 이다.

baseline-on-migrate: 이 옵션을 true 로 설정하면 실행 시 flyway_schema_history 테이블이 없으면 자동으로 생성한다.

flyway를 사용하는 경우 JPA의 ddl-auto 옵션을 validate 로 설정하는 것이 좋다. 이를 통해 스키마와 엔티티가 일치하는지 검증할 수 있다.

📌 flyway_schema_history

flyway_schema_history 테이블은 마이그레이션을 추적 및 관리하기 위해 사용되는 테이블이다. 이 테이블을 통해 flyway가 어떻게 동작하는지는 나중에 살펴보고, 테이블이 어떻게 구성되어 있는지 살펴보자. 주요 컬럼은 다음과 같다.

installed_rank: 마이그레이션이 적용된 순서를 나타내는 정수 값이다.

version: 마이그레이션 파일의 버전 번호이다. 이 버전을 기준으로 마이그레이션 순서를 결정한다.

checksum: 마이그레이션 파일의 해시 값이다. 이 값을 통해 이미 적용된 파일이 이후에 수정되었는지 검증한다.

📌 마이그레이션 파일

flyway는 설정된 경로에서 마이그레이션 파일을 스캔한다. 버전 번호를 기준으로 정렬되어 순서대로 적용된다. 각각의 파일이 적용될 때마다 flyway_schema_history 테이블이 업데이트된다.

파일명은 다음과 같은 구조를 가져야 한다. <Prefix><Version>__<Description>.sql

Prefix가 V 라면 특정 버전으로 업데이트, U 라면 이전 버전으로 롤백, R 이라면 버전과 상관없이 매번 실행되는 파일임을 의미한다.

Version은 V와 U에서만 사용되며, 숫자, 점, 언더바 등의 조합으로 구성된다. 새로 작성된 파일은 항상 이전보다 높은 버전을 사용해야 한다.

Description은 해당 파일에 대한 설명을 작성하면 된다.

📌 동작 원리

flyway가 데이터베이스와 연결되면 먼저 flyway_schema_history 테이블을 찾는다. 만약 존재하지 않으면 자동으로 해당 테이블을 생성한다. 이후 설정된 경로에서 마이그레이션 파일을 찾는다. 파일을 모두 찾으면 flyway_schema_history 테이블을 참고하여 아직 적용되지 않은(새로운 버전의) 마이그레이션 파일을 찾아 분류한다. 마지막으로 새로운 마이그레이션 파일을 버전 순으로 정렬하여 순차적으로 실행한다. 마이그레이션이 성공적으로 수행되면 flyway_schema_history 에 마이그레이션 내역을 기록한다.

마이그레이션 파일을 찾은 후 checksum 을 통해 파일 변경 여부 또한 확인한다. 만약 체크섬 값이 달라지면 오류가 발생한다.

📌 참고

https://ywoosang.tistory.com/18

https://velog.io/@suhongkim98/flyway%EB%A1%9C-%EB%8D%B0%EC%9D%B4%ED%84%B0%EB%B2%A0%EC%9D%B4%EC%8A%A4-%EC%8A%A4%ED%82%A4%EB%A7%88-%ED%98%95%EC%83%81%EA%B4%80%EB%A6%AC-%ED%95%98%EA%B8%B0

https://russell-seo.tistory.com/5

https://leeeeeyeon-dev.tistory.com/12