DB Migration Tool - Flyway

TopOfTheHead·5일 전

데이터베이스

목록 보기
12/13

DB 마이그레이션 Tool :
。DB Schema의 변경 이력을 추적하면서 코드로 관리하고, 버전 별로 구분하여 자동 적용하는 도구
▶ 수작업으로 SQL 작업을 수행하는게 아닌, 버전 관리 가능한 코드로 관리

。Git과 비슷한 형상관리 역할을 수행하며, UNDO를 수행할 수 있음.

。JAVA 기반의 마이그레이션 Tool : flyway, Liquibase

。Liquibase : YAML 기반 설정 및 NOSQL - RDBMS 간 호환성이 좋음.

。Flyway : SQL 기반이라 사용은 간편하지만, 호환성은 나쁨.

Flyway
。DB Schema 변경을 SQL 파일 버전 기반으로 관리하는 DB Migration Tool
▶ 테이블 생성 / 컬럼 추가 / 인덱스 변경 / 데이터 등의 작업을 SQL 파일 버전으로 관리하고 자동으로 실행하는 도구

。관리 대상 DB에 Migration 파일에 정의된 DB Schema로 자동으로 생성
▶ 수동으로 DB 구조 변경을 수행할 필요가 없음.

。DB 변경 이력을 Migration 파일( .sql )로 버전별로 관리하여 DB Schema의 형상 관리 및 변경 이력을 추적이 가능

。DB 버전 별로 Roll back을 수행하는 경우 flyway cli를 통해 UNDO를 수행

。JPA Buddy를 활용하여 Entity Class를 기반으로 Migration 파일을 생성 가능

데이터베이스 생성
。Flyway가 형상관리를 수행할 Flyway 관리 대상의 DB를 생성

DROP DATABASE 데이터베이스명;
CREATE DATABASE 데이터베이스명 ;

Flyway 의존성 설정
。Spring에서 기본적으로 Flyway에 대한 Starter를 제공

。starter 설정 후 프로젝트 생성 시 src/main/resources/db/migration 디렉토리가 자동 생성
▶ Flyway는 해당 디렉토리에서 Migration 파일을 저장 및 관리

application.yml을 통해 Auto-Configuration 설정
。AutoConfiguration을 통해 해당 설정의 객체가 Spring Bean으로 등록

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/데이터베이스명
    username: 유저명
    driver-class-name: com.mysql.cj.jdbc.Driver
    password: 비밀번호명
  jpa:
    hibernate:
      ddl-auto: none
  flyway:
    enabled: true 
    locations: classpath:db/migration
    baseline-on-migrate: false
    validate-on-migrate: true
  • JPA 사용 시 hibernate의 ddl-auto: none 또는 validate 설정
    。일반적으로 운영 환경에서만 설정하지만, Flyway에 의해 DB Schema 생성을 주도하기위해 hibernate에 의한 DB Table 생성 차단

  • flyway: enabled 기본 : true
    。flyway가 적용되도록 설정
    ▶ 설정 후 어플리케이션 구동 시 관리대상 DB에서 flyway_schema_history 테이블이 생성

  • flyway: locations 기본 : classpath:db/migration
    。flyway가 참조할 Migration 파일의 디렉토리 경로를 설정
    ▶ 기본적으로 src/main/resources 내 db/migration으로 설정

  • flyway: baseline-on-migrate 기본 : false
    。이미 테이블을 포함하는 DB를 Flyway 관리 대상으로 편입 시 사용하는 옵션
    ▶ 현재 DB 상태를 Baseline Version( 기준선 버전 )으로 등록하고 그 이전 migration을 적용하지 않도록 설정

    。주로 DB 내 flyway_schema_history 테이블이 없는 DB에 Flyway를 처음 도입할 때 true로 설정

    。true로 설정하면 Flyway가 flyway_schema_history 테이블이 없는 기존 DB에 대해 자동으로 baseline 작업 수행
    ▶ 이미 존재하는 테이블들을 기준으로 설정

    。 flyway는 기본적으로 어플리케이션 구동 시 DB를 비어있는 구조로 간주하여 만약 false 상태인 상태에서 Migration 파일을 실행 시 중복되는 기존 테이블이 존재하는 경우 충돌 발생
    ▶ 기존 테이블이 이미 존재하는 DB에 초기 Migration 파일(V1__init.sql)을 실행하면 table already exists 오류가 발생하므로 true 상태로 설정하여 해당 Migration 파일을 적용하지 않도록 설정

    。이미 Migration 파일이 존재하는 DB를 Flyway 관리 대상으로 등록 시 flyway:baseline-version: 을 추가로 선언
    ▶ 해당 버전의 Migration 파일부터 실행하도록 설정하여 이전 Migration 파일의 실행을 차단하여 충돌 방지

  • flyway:baseline-version:
    。baseline-on-migrate: true를 통해 DB를 Flyway 관리대상으로 등록 시 Migration 파일의 실행을 시작할 버전을 명시적으로 지정
    ▶ baseline-version: 4인 경우 V5__마이그레이션파일.sql부터 실행

    baseline-on-migrate 원리

    。기존 DB에 users, orders, products의 테이블이 존재하는 경우

    • DB를 처음 Flyway 관리 대상으로 등록하는 경우
      。간단하게 baseline-on-migrate: true로 설정하여 해당 DB Table Scheme를 Baseline으로서 설정
      ▶ false로 설정하는 경우, 이미 DB Table이 존재하는 상태에서 어플리케이션 구동 시 해당 DB table의 내용을 정의한 초기 Migration 파일 실행함으로써 충돌 발생
      flyway:
    enabled: true
    baseline-on-migrate: true
    validate-on-migrate: true
    • 이미 Migration 파일이 존재하는 DB를 Flyway 관리 대상으로 등록하는 경우
    V1__create_users.sql
V2__create_orders.sql
V3__create_products.sql

    ▶ V3 버전까지의 Migration 파일이 존재하는 경우

      flyway:
    enabled: true
    baseline-on-migrate: true
  	baseline-version: 3
    validate-on-migrate: true

    。baseline-version: 3으로 현재 DB 버전을 명시적으로 지정
    ▶ 어플리케이션 구동 시 해당 V3 이전 마이그레이션 파일은 실행되지않고, V4 이후 마이그레이션 파일만 실행됨



  • flyway: validate-on-migrate 기본 : true
    。Flyway가 Migration을 실행 전 기존에 적용된 Migration 파일( .sql )이 변경되었는지 검증 여부를 설정하는 옵션
    ▶ flyway_schema_history 테이블 내 checksum 값과 현재 Migration 파일을 비교하여 검증

    。동일 버전의 Migration 파일이 변경된 경우, 자동으로 검증 실패를 발생시켜 이미 운영 환경에서 반영 중인 Migration 파일이 수정되는 문제를 차단.
    ▶ 검증 실패 시 FlywayValidateException 발생 후 Migration 중단

    。운영 환경에서는 일반적으로 true로 설정하여 Migration 파일의 변경 여부를 감지하면서 무결성을 보장하도록 설정

flyway_schema_history
。DB 마이그레이션 실행 이력을 관리하기 위해 사용하는 메타데이터 테이블
▶ Flyway가 현재까지 어떤 Migration 파일을 실행했는지 기록하면서 관리

。현재 DB가 어떤 버전의 Migration 파일까지 반영되었고, 어떤 Migration 파일을 적용하지 않았는지 판단 시 활용
▶ 어플리케이션 실행 시 flyway_schema_history를 통해 반영하지 않은 Migration 파일을 식별하여 적용

。checksum을 통해 Migration 파일의 무결성을 검증
▶ 이미 DB에 실행된 Version의 마이그레이션 파일을 수정하면 checksum 오류가 발생하므로 수정하면 안된다.

。특정 Migration 파일에 해당하는 데이터 행을 삭제 후 재실행 시 해당 Migration 파일을 실행하게됨.
▶ flyway_schema_history 테이블 자체를 삭제 시 처음부터 실행

▶ flyway: enabled: true를 통해 DB를 Flyway 관리 대상으로 초기 등록 시 생성

  • DB 내부 구조

    installed_rank : Migration 파일 실행 순서
    version : Migration 버전
    ▶ 지금까지 실행한 Migration 파일의 버전을 기록

    description : Migration 설명
    type : SQL/JDBC 여부
    script : 실행된 Migration 파일명
    checksum : 파일 checksum
    ▶ 검사합: checksum을 기반으로 Migration 파일의 수정여부를 검증

    installed_by : 실행 사용자
    installed_on : 실행 시간
    execution_time : 실행 시간 ( ms )
    success : 성공 여부

Migration 파일
。DB Schema 변경 이력을 버전단위로 관리하기 위한 SQL 파일
▶ DB 구조 변경을 기록

。 spring: flyway: locations로 등록된 디렉토리 내 migration 파일을 생성 및 관리
▶ 기본 : src/main/resources/db/migration

。flyway_schema_history 테이블에 등록된 Mgration 파일 실행 기록을 기준으로 Flyway는 다음에 실행할 Migration 파일을 식별 후 실행
▶ flyway_schema_history 테이블 삭제 후 실행 시 이전 실행 기록이 없으므로, 처음부터 db/migration 내 V1 -> .... 순서로 Migration 파일을 자동 실행

ex) V1__create_boards.sql 

create table `boards`(
    id bigint not null primary key auto_increment,
    name varchar(255)
)

Migration 파일명 컨벤션
。해당 파일명 컨벤션을 준수하지 않으면, Flyway에 의해 식별되지 않는다.

{Prefix}{Version}__{Description}.sql
ex ) V1__create_user_table.sql


Prefix :

  • V ( Versioned Migration )
    。범용적으로 사용되며 마이그레이션 파일 버전을 의미하는 접두사
    ▶ DB Schema를 버전 순서대로 변경 시 사용

    。V로 지정된 마이그레이션 파일은 한번 실행되면 재실행되지않고, 버전 번호 기준으로 실행
    ▶ 이미 DB에 실행된 Version의 마이그레이션 파일을 수정하면 checksum 오류가 발생하므로 수정하면 안된다.

  • R ( Repeatable Migration )
    。해당 파일에 변경사항이 존재하는 경우에 어플리케이션 구동 시 마이그레이션을 실행하기위한 파일임을 표시하는 접두사
    ex ) R__create_view.sql

    。VIEW 생성 시 주로 활용하여 수정내용을 기반으로 마이그레이션 실행

    。버전 번호를 기재하지 않고, 파일 내용 변경 시 재실행
    ▶ flyway_schema_history의 checksum 비교를 통해 재실행 여부 판단

  • U ( Undo Migration )
    。특정 Versioned Migration을 수동으로 UNDO하기 위한 파일임을 표시하는 접두사
    ▶ V Migration의 Rollback 용도로서 활용
V2__add_email_column.sql // email 컬럼 추가
U2__remove_email_column.sql // email 컬럼 삭제

。일반적으로 활용되지는 않는다.


Version :
。해당 Migration 파일의 버전을 지시하며, 접두사 뒤 ( V, U )에 숫자, _, .를 사용하여 버전을 표기

。Flyway는 어플리케이션 구동 시 해당 버전 순서대로 자동으로 실행
ex ) V1.1 -> V1.2 -> ..., V1_1_1 -> V1_1_2 -> ....

。application.yml에 flyway:baseline-version: 버전 설정 시 해당 버전의 마이그레이션 파일은 전부 적용됨을 간주하여 다음 버전의 Migration 파일부터 차례대로 실행.


Description :
。해당 Migration 파일을 설명하는 부분
▶ Commit Message같은 느낌.

JPA Buddy를 활용하여 Entity를 기반으로 Flyway Migration 파일 생성

  • Flyway 의존성 정의 및 DB 생성


    create database demo-flyway;
    ▶ Flyway에 의해 관리될 DB 생성

  • application.yml에서 Flyway 관련 설정 수행
spring:
  datasource:
    url: jdbc:mysql://localhost:3304/demo-flyway
    username: root
    driver-class-name: com.mysql.cj.jdbc.Driver
    password: wjd747
  jpa:
    hibernate:
      ddl-auto: none
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: false
    validate-on-migrate: true

。초기 설정이므로, baseline-on-migrate: false를 설정
▶ DB를 flyway 관리대상으로 편입 시에만 true로 설정

。ddl-auto: none을 설정하여 hibernate의 DDL에 의해 DB Schema가 생성되지 않도록 설정
▶ flyway의 Migration 파일 의해 DB Schema가 생성되므로.

  • 초기 Application 구동


    ▶ Migration 파일을 정의하지 않았으므로, 식별되지 않았으며 DB에 자동으로 flyway_schema_history 테이블이 생성되며 Flyway 관리대상으로 등록

  • DB Entity 생성 및 해당 Entity 설정을 기반으로 JPA Buddy를 활용하여 Migration 파일 생성
@Entity
public class Post {
	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private int id;
	//
	private String title;
}


。Intellij의 좌측 ... -> Persistence를 선택

。Persistence에서 생성된 Entity 클래스 우클릭 -> New -> Flyway Migration으로 접근

。 경로를 src/main/resources/db/migration으로 설정 및 파일명 설정
▶ 파일명은 컨벤션을 지켜서 생성

。 DB Entity 설정 기반의 DDL을 포함하는 Migration 파일 생성


。어플리케이션 구동 시 해당 버전 Migration 파일을 식별 후 파일 내 DDL을 실행하여 테이블 생성
▶ V1__create_post_table.sql이므로 Flyway에 의해 버전1로 등록되어 실행

。flyway_schema_history 테이블에서 Migration 파일의 실행기록이 보관
▶ Flyway는 해당 테이블을 참조하여 어플리케이션 실행 시 V1 까지의 Migration 파일을 실행하지 않고, V2 부터의 Migration 파일을 실행

  • Entity 클래스 수정 후 Migration 파일 생성
@Entity
public class Post {
	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private int id;
	//
	private String title;
	//
	private String content;
}

▶ content 필드 추가



。flyway_schema_history 테이블에 등록된 기록에 의해 이전 V1__create_post_table.sql은 실행되지 않고, 기록에 없는 V2__add_content_column.sql이 flyway에 의해 실행됨
▶ 실행 이후 flyway_schema_history 테이블에 등록되어 이후 재실행 시 V3 Migration 파일부터 실행

。flyway_schema_history 테이블은 DB Table Schema의 변경을 마이그레이션 파일 버전별로 추적하면서 버전관리를 수행

profile
TopOfTheHead
공부기록 블로그
이전 포스트

DB Table 제약조건

다음 포스트

CQRS

0개의 댓글