데이터베이스 스키마는 애플리케이션 코드만큼이나 중요한 자산이다. 테이블, 컬럼, 인덱스, 제약조건은 시간이 지남에 따라 계속 변화하며 이 변화가 누적되면 현재 DB 상태가 어떤 과정을 거쳐 만들어졌는지 파악하기 어려워진다. 환경마다 스키마 상태가 다르거나, 누가 언제 어떤 DDL을 실행했는지 알 수 없다면 배포와 유지보수는 점점 위험해진다.
Flyway는 이러한 문제를 해결하기 위한 데이터베이스 마이그레이션 도구다. DB 스키마 변경을 코드처럼 파일로 관리하고, 버전과 히스토리를 기반으로 자동 적용과 검증을 수행한다. 애플리케이션과 함께 DB 변경 이력을 관리함으로써 예측 가능한 배포와 안정적인 운영을 가능하게 한다.
Flyway Migration 개념
Flyway의 핵심 개념은 매우 단순하다. 실행할 DDL과 DML을 마이그레이션 파일로 작성하고, 정해진 규칙에 따라 순서대로 실행하는 것이다. Flyway는 기본적으로 classpath:db/migration 경로를 스캔해 실행 가능한 마이그레이션 목록을 만든다.
처음 실행될 때 Flyway는 flyway_schema_history 테이블을 생성한다. 이 테이블은 Flyway의 핵심 구성 요소로, 각 마이그레이션의 버전, 설명, 실행 시간, 성공 여부, 체크섬 정보를 기록한다. 이후 Flyway는 파일 시스템에 존재하는 스크립트와 히스토리 테이블을 비교해 아직 적용되지 않은 스크립트만 실행한다.
중요한 점은 Flyway가 데이터베이스 자체의 변경을 추적하지 않는다는 것이다. Flyway는 오직 “마이그레이션 스크립트”와 “히스토리 테이블”만을 기준으로 판단한다. 따라서 테이블을 직접 수정하거나 기존 스크립트를 임의로 변경하면 Flyway는 이를 자동으로 감지하지 않는다. 이 구조를 이해하는 것이 Flyway를 올바르게 사용하는 첫 단계다.
Flyway Version과 History
Flyway 마이그레이션 파일은 명확한 네이밍 규칙을 따른다. 대표적인 형식은 V1__create_table.sql 과 같다. 접두사(V), 버전 번호(1), 구분자(__), 설명(create_table)로 구성된다. 이 규칙 덕분에 Flyway는 파일 이름만으로 실행 순서를 결정할 수 있다.
Versioned Migration(V)은 한 번만 실행된다. 실행이 완료되면 flyway_schema_history 테이블에 기록되며, 같은 버전은 다시 실행되지 않는다. 반면 Repeatable Migration(R)은 파일 내용이 변경되면 체크섬 비교를 통해 재실행된다. 뷰, 함수, 프로시저처럼 항상 최신 정의를 유지해야 하는 경우에 주로 사용된다.
히스토리 테이블의 체크섬은 파일 내용 전체를 기준으로 계산된다. 이미 실행된 V 스크립트를 수정하면 Flyway는 validate 단계에서 체크섬 불일치를 감지하고 애플리케이션 실행을 중단한다. 이는 “이미 적용된 이력은 바꾸지 않는다”는 Flyway의 철학을 강제하기 위한 장치다. 필요하다면 repair 명령으로 히스토리를 조정할 수 있지만, 운영 환경에서는 신중하게 사용해야 한다.
Flyway 실전에서의 주의점
Flyway를 사용할 때 가장 중요한 원칙은 “기존 마이그레이션은 수정하지 않는다”는 것이다. 스키마를 변경해야 한다면 새로운 버전의 마이그레이션 파일을 추가해야 한다. 이 방식은 다소 번거로워 보일 수 있지만, 모든 변경 이력이 순서대로 남기 때문에 환경 간 차이를 최소화할 수 있다.
또 하나의 주의점은 DB를 직접 수정하는 행위다. 운영 중 테이블에 직접 접근해 컬럼을 삭제하거나 수정하더라도 Flyway는 이를 인지하지 못한다. Flyway의 관점에서 히스토리에 기록된 버전이 그대로라면 스키마는 “정상” 상태다. 따라서 Flyway를 도입했다면 모든 구조 변경은 마이그레이션 스크립트를 통해 수행해야 한다.
Flyway는 DB 스키마를 선언적으로 관리하는 도구다. 자동으로 차이를 맞춰주는 도구가 아니라, “우리가 정의한 스크립트”를 정확히 실행하고 기록하는 역할을 한다. 이 개념을 이해하고 사용한다면, 새로운 환경에서도 예측 가능한 DB 구성이 가능해진다.
정리하면, Flyway는 데이터베이스를 코드처럼 다루기 위한 도구다. 버전, 히스토리, 리뷰, 배포 파이프라인 안에서 DB 스키마를 관리하고 싶다면 Flyway는 충분히 검증된 선택지다. 단, 그 철학과 동작 방식을 이해한 상태에서 사용하는 것이 무엇보다 중요하다.