Flyway

배경

• 개발을 진행하다보면 엔티티의 구조가 변경되고, 이로 인해 데이터베이스의 스키마도 변경되는 일이 발생함

• 소프트웨어 소스 코드는 Git과 같은 형상관리 툴을 사용하여 버전 관리를 진행했다면, 데이터베이스는 이력을 관리할 방법이 없었음

  • 일일이 스키마 수정을 위한 DDL을 각 환경별로 모두 실행해주어야 했음

• 물론, 로컬 개발 환경이나 개발 서버에서는 하이버네이트 설정 중 ddl-auto을 create나 create-drop, update 옵션을 사용하면 엔티티 구조에 맞춰 실행할 수 있지만, 운영 환경에서는 해당 설정이 불가능함

  • 프로덕션 서버는 실제 유저들의 데이터가 저장되어있기 때문에 테이블을 DROP할 수 없고, 테이블 ALTER TABLE과 같은 데이블 스키마를 변경하는 DDL을 사용해야 함

  • 하지만 이렇게 DDL을 작성하고 프로덕션 서버에 실행시키는 작업은 매우 번거롭고, 사람의 실수가 발생하기 쉬우며 형상관리도 어려움.

• 하지만 flyway를 사용한다면 이러한 문제들을 해결할 수 있음

Flyway란?

• 데이터베이스 형상 관리를 위한 오픈소스 데이터베이스 마이그레이션 툴

• 데이터베이스의 DDL 이력을 쌓아서 관리하는 툴로, DB의 변경사항을 추적하고 업데이트나 롤백을 보다 쉽게 도와주는 도구

• 마이그레이션 Script는 SQL 또는 Java로 작성 가능

Flyway 사용 장점

1. 버전 관리 및 히스토리 추적

   • 각각의 데이터베이스 스키마 변경이 버전으로 기록되고, 변경이력을 추적할 수 있음

2. 자동 마이그레이션

   • flyway는 어플리케이션이 시작될 때 자동으로 마이그레이션을 수행함

   • 이를 통해 개발자가 수동으로 데이터베이스 변경을 관리하지 않아도 됨

3. CI/CD 파이프라인 통합

   • Flyway는 CI/CD 파이프라인에 자동 마이그레이션을 통합할 수 있어, 데이터베이스 변경과 애플리케이션 배포를 함께 관리할 수 있음

Flyway 동작 방식

1. schema history table 생성(상태 저장)

• Flyway를 통해서 마이그레이션을 처리하고자 할 때, Flyway 첫 실행시에는 연결된 대상 데이터베이스에 자동으로 SCHEMA_VERSION table을 생성함

  • SCHEMA_VERSION: flyway가 스키마 변경 이력을 관리하는 메타데이터 테이블

  

  • 왼쪽 사진에서 두 개의 마이그레이션(데이터베이스 스키마 변경 sql이 기록된)을 가지고 있고, 데이터베이스가 비어있기 때문에 오른쪽 사진과 같이 SCHEMA_VERSION table을 신규로 생성함

2. 마이그레이션 실행

• flyway는 즉시 파일시스템 혹은 애플리케이션의 마이그레이션을 위해 지정된 클래스패스에서 SQL 혹은 JAVA 파일을 탐색함

• 탐색된 파일들은 버전에 따라서 번호 순서대로 정렬하여 실행함

3. schema history table 업데이트

• 마이그레이션이 실행되고 나면 SCHEMA_VERSION table에 실행 이력을 저장하게 되고, 테이블에서 버전정보, 체크섬, 성공여부 등을 확인할 수 있음

• 초기 상태 완료 후에는 버전정보를 저장하고 있기 때문에, 다음 마이그레이션시에는 이전 버전 또는 현재 버전과 같은 마이그레이션 파일은 무시함

Flyway 마이그레이션 파일명 규칙

• flyway는 마이그레이션 대상 파일명과 경로로 파일을 구분하고 스캔함

• 기본 경로인 /resources/db/migration에 존재하는 파일들을 스캔하며, 해당 경로는 변경이 가능함

  • 이 경로 변경을 활용하여 아예 다른 데이터베이스의 스키마 변경도 진행할 수 있음 (h2에서 MySql으로)

• prefix

  • V - 버전 마이그레이션 (Versioned Migrations)

  • U - 취소 마이그레이션 (Undo Migrations)

  • R - 반복 마이그레이션 (Repeatable Migrations)

• version

  • 버전을 나타내며, 숫자와 점(.) 그리고 언더바(_) 조합으로 구성됨

  • 버전 마이그레이션과 취소 마이그레이션에서만 사용하고, 반복 마이그레이션에서 사용하면 에러가 발생함

• separator

  • 설명 부분을 구분하기 위한 구분자이며, 반드시 언더바 2개(__)를 사용해야 함

• description

  • 스키마 버전 테이블에 저장시 설명으로 사용됨

• suffix

  • 확장자 기본은 .sql

버전 마이그레이션 Versioned Migrations

• Flyway의 핵심 기능

• 마이그레이션 스크립트의 최신 버전과 현재 데이터베이스의 스키마 버전을 비교하고, 차이점이 있다면 마이그레이션 스크립트를 순차적으로 실행하여 최신 스키마와 격차를 좁힘

• 예시)

  • 마이그레이션 버전이 1부터 9까지 있다고 가정

  • 현재 개발환경의 데이터베이스 스키마 버전이 5일 때, 최신 버전에 대해 마이그레이션을 실행하면 마이그레이션 스크립트 6부터 9가 순차적으로 실행됨

취소 마이그레이션 Undo Migrations

• Flyway Teams 유료 버전에서만 사용 가능한 기능으로, 마이그레이션을 롤백하는 스크립트를 작성해야 함

• 이 스크립트는 마이그레이션의 작업을 반대 방향으로 데이터베이스 스키마를 변경함

• 프로덕션 환경에서는 신중하게 사용해야 함

• 롤백이 실제로 수행되기 전에는 항상 백업을 만들고, 롤백 후에는 데이터의 일관성을 확인하는 것이 좋음

반복 마이그레이션 Repeatable Migrations

• 모든 마이그레이션 스크립트가 실행된 이후 실행되는 스크립트

• 반복 마이그레이션끼리는 description 순서대로 실행됨

• 한 번 실행되며, 파일이 변경되어 체크섬이 변경된 경우 다시 실행됨

실행명령 Command

무료 버전의 flyway에서 제공하는 명령어는 6가지이고, 유료 버전에는 check, snapshot, undo를 제공함

Migrate

• 스키마 정보를 데이터베이스에 마이그레이션

Info

• 모든 마이그레이션 상세정보 출력

• 마이그레이션의 성공여부와 실행 시간 확인 가능

Clean

• 데이터베이스의 schema_version 테이블을 포함한 모든 테이블, 뷰, 프로시저등을 drop(삭제)

• 운영환경에서 실행주의

Validate

• 데이터베이스에 적용된 마이그레이션 정보의 유효성 검증

Baseline

• 특정 버전에서 기존 데이터베이스에 flyway를 도입하기 위해 사용

• 베이스라인 버전까지의 모든 마이그레이션은 무시

Repair

• flyway_schema_table의 이슈를 수리하기 위해 사용

• 방식은 두가지

  • 실패한 마이그레이션 항목 제거 (DDL 트랜잭션을 지원하지 않은 데이터베이스만 해당 ex) SQLite, MySQL, Oracle)

  • 적용된 마이그레이션의 체크섬, 설명, 타입들을 사용 가능한 마이그레이션의 체크섬으로 재정렬

Ref

• 달록의 데이터베이스 마이그레이션을 위한 Flyway 적용기
• Flyway docs
• Flyway
• Flyway와 DB Migration / 우리 팀에서 Flyway를 사용하는 이유
• Spring docs
• 나만 모르고 있던 - Flyway (DB 마이그레이션 Tool)