개요

회사 프로젝트 규모가 커지고 팀원이 많아질수록 데이터베이스(이하 DB) 싱크를 맞추는게 생각보다 쉽지가 않았다. 이로 인한 스트레스를 줄이고자 코드를 형상 관리해주는 Git과 같은 좋은 툴이 있나 찾아보았고, 최종적으로 Spring 진영에서 많이들 사용하고 있는 Flyway를 적용해보기로 결정하였다.

Flyway

앞서 설명한 것처럼 Flyway는 DB의 형상 관리를 담당해주는 오픈소스 DB Migration Tool이다.

공식 홈페이지

Convention

Flyway가 읽어들이는 SQL 스크립트의 경우 정해져있는 네이밍 규칙이 있다.

Naming Convetion 관련 링크

• 공통
  • V, U, R (PREFIX) + Version, __ (언더바 2개) + Description + .sql 형식을 따라야함
• ex) V202407021214__init.sql

1. Versioned Migrations
   • 주로 사용하게 되는 기능
   • 흔하게들 작업하는 내용을 SQL로 작성
2. Undo Migrations
   • 유료 기능
   • 기존에 적용된 Migration을 롤백할 수 있음
   • V로 롤백하는 것보다 변경 추적 및 테스트에 용이함
3. Repeatable Migration
   • 반복적으로 실행시키고 싶은 SQL을 작성
   • 주로 뷰, 프로시저, 함수, 트러기와 같은 SQL을 작성

Step

현재 진행 중인 프로젝트에 Flyway를 적용하려면 아래와 같은 과정을 거쳐야한다.

1. build.gradle 의존성 추가

	implementation("org.flywaydb:flyway-core")
	runtimeOnly("org.flywaydb:flyway-sqlserver")

2. 환경 설정

  flyway:
    enabled: true
    baseline-on-migrate: true #flyway_schema_history 자동 생성
    baseline-version: 1       # 시작 버전
    locations: classpath:db/migration # default

3. 아래와 같이 path directory 설정 (flyway.locations)
   

   • 이미지와 같이 Active Profile 기준으로 sql을 별도로 관리하고 싶다면 classpath:db/migration/local과 같이 yml 파일에 설정해줘야 함

4. DB 형상 관리를 추적하기 위한 SQL 스크립트 작성
   

   -- V202406111208__init.sql 파일 내부
   
   -- init Flyway SQL Script
   -- 기존에 존재하는 DB에 Baseline을 설정해주기 위한 공백 파일

• SQL 스크립트가 존재하지 않는 경우 서버가 실행되지 않기에 실제 DB에 변동 사항이 없더라도 반드시 1개의 SQL 스크립트가 존재해야 함

5. 서버 실행 후 flyway_schema_history 테이블 확인
   • 아래와 같이 DB 형상 관리를 위한 Table이 생성되어있는 것을 확인할 수 있음
     
   • 첫 번째 로우를 통해 Flyway Baseline이 설정된 것을 확인할 수 있고, 두 번째 로우를 통해 해당 프로젝트의 DB의 형상 관리를 시작했음을 알 수 있음

주의할 점

0. 상단에 언급한 것처럼 DB를 추적하기 위해서 반드시 비어있는 SQL 스크립트라도 작성을 해줘야 함
1. 한 번 생성한 SQL 스크립트는 지워선 안 됨
   • Flyway는 스크립트 파일의 Version에 적힌 숫자값과 flyway_schema_history 테이블에 저장된 checksum 값을 보고 형상 관리를 수행하기에 삭제를 하면 추적이 불가능해짐
2. Version의 값은 오름차순으로 적어야 함
   • 형상 관리를 추적할 때 Version의 값이 작은 순부터 큰 순으로 추적을 함
   • 이 때, Version의 값이 오름차순이 아닌 경우 에러가 발생함
3. Version은 단순한 숫자보단 복잡한 숫자로 표기를 추천
   • 혼자 관리하는 경우 1, 2 이렇게 간단한 숫자로 표기해도 중복의 우려가 적겠지만 여러명이 함께 관리하는 프로젝트인 경우 Version의 중복 가능성을 배제하지 못함
   • 현재 우리팀의 경우 연도, 월, 일, 시간, 분을 합쳐 Version으로 표기
4. 이유는 모르겠으나 가끔씩 Version이 가지고 있는 checksum의 값이 Flyway가 내부적으로 가지고 있는 값과 일치하지 않아 에러가 발생함
   • 아직까지 이유를 찾지 못하였으나 위 문제가 발생하는 경우, 해당 Version의 checksum 값을 서버 로그에 찍힌 값으로 강제 업데이트 후 적용 시 정상 동작

마치며

현재까지 Flywaya를 적용하고 나서의 만족도는 매우 크다. 물론 아직까지 적용 초기 단계이고 모든 팀원들이 DB 변경에 참여하고 있지는 않아 발견되지 않은 문제들이 많겠지만, 개발 후 실서버 배포 시점에 항상 느꼈던 스트레스가 현저히 줄었고 Human Risk 또한 확실하게 줄어든게 체감이 된다.

Flyway 도입을 망설이고 계시거나 도입을 하려고 하지만 선뜻 방법을 모르시겠는 개발자분들에게 도움이 되셨으면 좋겠습니다!!