Spring Boot에서 ddl-auto 옵션을 사용하면 엔티티 기반으로 테이블이 자동 생성되지만, 이 경우 애플리케이션 실행 시 Hibernate가 임의로 스키마를 변경해버려 예측 불가능한 문제가 생길 수 있다.

그래서 ddl-auto: none으로 설정하고 직접 DB에 접속해 수동으로 쿼리를 실행하는 방법이 있지만, 서비스가 커지면서 테이블이 늘고 구조가 자주 바뀌다 보니 변경 내역을 놓치기 쉽고 관리가 되지 않았다. 결국 수동 관리 방식은 너무 복잡하고 유지보수가 어렵다는 한계에 부딪혔다.

이 문제를 해결하기 위해 Flyway를 도입하여 스키마를 버전별로 관리하고 자동으로 적용할 수 있도록 했다.

• 버전 관리: flyway_schema_history 테이블을 사용해 마이그레이션 내역을 기록한다. (버전, 실행 시간, 체크섬, 상태 등)
• 애플리케이션 시작 시 검증: 애플리케이션 시작 시 Flyway는 flyway_schema_history를 확인하고, 아직 적용되지 않은 마이그레이션만 실행된다.
• 버전 규칙: 이미 적용된 버전 이하의 마이그레이션 파일은 실행되지 않는다.
• 체크섬 검증: 동일 버전의 파일이 DB에 기록된 체크섬과 다르면 오류가 발생한다.(체크섬 달라짐)
• 스키마 변경 추적: 모든 DDL 변경 사항이 마이그레이션 파일로 관리되기 때문에 변경사항 추적 가능
• 직접 DB에 접속해서 수동으로 쿼리를 날릴 필요 없이 잦동으로 마이그레이션이 반영된다.

예시

V1__create_users_table.sql
V2__add_posts_table.sql

• Flyway 마이그레이션 파일은 환경별로 실행되는데, DB마다 지원하는 문법이 달라 문제가 발생할 수 있다.
  • 예: PostgreSQL에서는 SERIAL, BIGSERIAL, UUID 같은 타입을 기본적으로 지원하지만, H2는 지원하지 않아서 테스트 환경에서 에러가 발생한다.
• 따라서 마이그레이션 작성 시, PostgreSQL 기준으로 작성하되 H2 호환성도 반드시 체크해야한다.

• flyway clean: DB 전체를 초기화하므로 운영 환경에서는 절대 사용 금지
• flyway repair: 체크섬을 덮어쓰는 기능으로, 잘못 사용하면 스키마 불일치 문제 발생가능성. 단순 주석 변경 정도에만 제한적으로 활용해야한다.