프로젝트를 진행하면서 DB 스키마 버전을 관리하기 위해 Flyway를 사용하고 있습니다.
이번에는 단순한 실수로 인해 애플리케이션이 기동되지 않는 오류를 경험했습니다.
Flyway란
Flyway는 DB 마이그레이션 도구로,
V1__init.sql, V2__add_table.sql처럼 버전을 붙인 SQL 파일을 순서대로 실행하여 데이터베이스 스키마를 관리합니다.
한 번 실행된 마이그레이션 파일은 그 내용의 해시(체크섬) 을 DB 내부의 flyway_schema_history 테이블에 저장해둡니다.
이후 애플리케이션을 다시 실행할 때 파일 내용이 이전과 달라지면 (주석, 띄어쓰기, 줄바꿈까지 포함)
체크섬 불일치(Migration checksum mismatch) 로 간주하고 실행을 중단합니다.
증상
이미 배포되어 적용된 V2__add_table.sql 파일에서
단순히 주석만 삭제했는데도 Flyway가 이를 다른 파일로 인식했습니다.
Spring Boot 실행 중 다음과 같은 오류가 발생했습니다.
Migration checksum mismatch for version 2
Detected applied migration not resolved locally
이 에러로 인해 애플리케이션이 기동되지 않았습니다.
원인 및 해결
앞서 말했듯이, Flyway는 SQL 파일의 내용 전체를 체크섬으로 관리하기 때문에 주석이나 줄바꿈 같은 코드 외적 변경도 모두 다른 버전으로 판단합니다.
즉, 이미 적용된 마이그레이션 파일을 수정하는 것은 데이터베이스 히스토리와 불일치를 일으켜 에러로 이어지게 됩니다.
가장 단순한 해결 방법은 파일을 원래 상태로 되돌리는 것입니다. 주석을 삭제하기 전 버전으로 복구한 뒤 애플리케이션을 재실행하니 정상적으로 기동되었습니다.
'Error log' 카테고리의 다른 글
| WebSocket 연결 오류 발생 및 해결 과정 (0) | 2025.11.17 |
|---|---|
| VS Code에서 org.springframework.messaging 인식 안 됨 해결 (0) | 2025.11.11 |
| Spring Boot JWT 라이브러리 IDE 인식 문제(2025.11.01) (0) | 2025.11.01 |