Flyway 사용 중 마주한 문제와 해결 과정
1. Flyway 사용 배경
프로젝트를 진행하다 보면 데이터베이스 스키마 변경은 필연적으로 발생한다. 그러나 수동 SQL 관리나 환경별 개별 반영 방식으로 인해 환경 간 스키마 불일치, 변경 이력 추적의 어려움, 각종 휴먼 에러와 같은 문제가 발생하곤 한다. 이러한 문제를 해결하기 위해 Tenant 팀에서는 데이터베이스 변경 이력을 체계적으로 관리할 수 있는 Migration 도구인 Flyway를 사용하고 있다.
Flyway는 버전이 부여된 SQL 스크립트를 차례대로 실행하고, 실행 이력을 테이블로 관리하여 데이터베이스 변경을 통제하는 Migration 도구다. 이 글에서는 Flyway를 사용하면서 겪었던 문제를 회고하고, 동시에 사용 시 주의해야 할 점을 중심으로 정리한다.
2. 문제 경험 1 – Checksum 불일치
Flyway를 처음 사용하면서 가장 먼저 겪었던 문제는 체크섬 불일치 오류였다. 특정 환경에서 데이터 정합성 문제가 발생하여 이를 해결하기 위해 다른 환경의 정상 데이터를 기준으로 복구 작업을 진행한 적이 있었다. 이 과정에서 전체 데이터를 덮어쓰는 방식으로 작업을 수행하였고, 그 결과 flyway_schema_history 테이블까지 함께 변경되었다. 이후 애플리케이션을 재기동하였을 때 Flyway의 검증 단계에서 checksum mismatch 오류가 발생하며 애플리케이션이 정상적으로 실행되지 않았다.
이 문제의 원인을 분석해 보면 Flyway의 동작 방식과 관련이 있다. Flyway는 Migration 파일이 최초 실행될 때 파일 내용을 기준으로 체크섬을 생성하고 이를 flyway_schema_history 테이블에 저장한다. 이후 애플리케이션이 실행될 때마다 해당 테이블에 저장된 체크섬과 현재 파일의 체크섬을 비교하여 변경 여부를 검증한다. 즉, 이미 실행된 Migration 파일이 변경되었거나 DB에 기록된 이력과 실제 파일이 일치하지 않는 경우, Flyway는 데이터베이스 상태를 신뢰할 수 없다고 판단하고 실행을 차단한다.
이 경우 다른 환경의 데이터를 덮어쓰는 과정에서 flyway_schema_history 테이블까지 함께 변경되면서, DB에 저장된 체크섬 값과 실제 Migration 파일의 체크섬 값이 달라지게 되었고, 그 결과 오류가 발생하게 된 것이다. 문제를 빠르게 해결하기 위해 데이터 복구 시 flyway_schema_history 테이블은 제외하고 나머지 테이블만 복구하도록 수정한 뒤 다시 작업을 진행하였고, 이후 애플리케이션을 재기동하자 정상적으로 Flyway 검증이 통과되었다.
3. 문제 경험 2 – Migration 버전 충돌
두 번째로 겪은 문제는 Migration 버전 충돌이었다. 신규 기능 개발 과정에서 Migration 파일을 추가하고, 로컬 환경에서 main 브랜치 병합 테스트를 진행하던 중 동일한 버전 번호를 가진 Migration 파일이 두 개 존재하여 오류가 발생하였다. 이 문제는 두 명의 개발자가 동시에 작업을 진행하면서 발생하였다. 각자 Migration 파일을 생성하는 과정에서 사전에 버전 번호를 공유하지 않았고, 그 결과 동일한 버전 번호가 중복으로 사용되었다. Git 상에서는 파일이 정상적으로 병합되었기 때문에 문제가 없는 것처럼 보였지만, 실제 애플리케이션 실행 시점에서 Flyway가 어떤 Migration을 먼저 실행해야 할지 판단하지 못하면서 오류가 발생하게 되었다.
해당 문제는 main 브랜치를 이전 상태로 되돌린 후 Migration 버전을 재정렬하는 방식으로 해결하였다. 먼저 반영된 스크립트를 제거하고 데이터베이스를 롤백하였고, 논의 후 첫 번째 스크립트를 먼저 적용한 뒤, 새로운 Migration 파일은 충돌이 발생하지 않도록 다음 버전으로 재작성하였다. 이 문제는 코드 레벨에서는 드러나지 않기 때문에 더 큰 주의가 필요하다. 일반적인 코드 충돌은 Git 병합 과정에서 바로 확인할 수 있지만, 해당 문제는 애플리케이션 실행 시점에 오류가 발생하기 때문이다. 만약 이러한 상태로 운영 환경까지 반영되었다면 단순한 수정으로 해결되지 않고 더 큰 장애로 이어질 수 있다는 점에서 더욱 주의를 기울여야겠다.
4. 정리
일련의 경험을 통해 전달하고자 하는 주의 사항은 다음과 같다.
- flyway_schema_history 테이블은 절대 덮어쓰지 않는다
- 이미 실행된 Migration 파일은 수정하지 않는다
- Migration 파일 생성 전 반드시 최신 버전을 확인한다
- 변경 사항을 반드시 팀원과 사전에 공유하여 버전 충돌을 막는다
처음 Flyway를 접했을 때는 단순히 데이터베이스 변경을 적용하는 기능만을 하는 도구라고 생각했다. 그러나 다양한 오류를 겪으면서 Flyway는 데이터 자체보다 “변경 이력의 신뢰성”을 더 중요하게 다루는 도구라는 점을 깊게 체감했다. 또한 이러한 도구를 안정적으로 운영하기 위해서는 기술적인 이해뿐만 아니라 팀원 간의 커뮤니케이션과 협업 방식 역시 중요한 요소라는 점을 함께 느끼게 되었다.
Yujin Jeong