TL;DR — 이미 적용된 마이그레이션 SQL에 주석 세 줄을 넣었다가 체크섬 불일치로 서버가 못 뜼었다. 더 큰 문제는 통합 테스트가 이걸 절대 잡지 못한다는 것 — 매번 빈 DB로 시작하므로 기존 DB의 적용 이력과 비교할 일이 없다. 파일 CRC32를 고정하는 테스트로 막았다.

배경

• 프로젝트/기능: DeployHub — Flyway가 관리하는 MySQL 스키마
• 환경: Java 17, Spring Boot 3.5, MySQL 8, Testcontainers

문제 (증상)

• 이미 운영 DB에 적용된 마이그레이션 파일에 설명 주석을 추가했다
• 서버가 기동 실패 — 체크섬 불일치(Migration checksum mismatch)
• 코드를 고친 게 아니라 주석만 넣었는데도 죽으므로 원인을 오인하기 쉽다

원인 분석

• Flyway는 마이그레이션의 파일 내용 전체로 체크섬을 낸다. 주석도 내용이므로 한 줄이면 충분히 깨진다
• 적용 이력은 DB의 flyway_schema_history에 있고, 파일은 저장소에 있다. 둘이 어긋나는 순간 기동이 막힌다
• 그런데 통합 테스트는 Testcontainers로 매번 빈 DB를 띄운다 — 적용 이력이 없으니 비교할 대상이 없고, 항상 처음부터 전부 적용해 통과한다
• 즉 이 부류는 테스트 전략상 구조적으로 보이지 않는 영역이다. 케이스를 더 써도 안 잡힌다

해결

• 마이그레이션을 한 파일로 통합하고, 기존 DB는 이력을 재기준선(baseline)으로 잡아 넘어오게 했다
• 그리고 마이그레이션 파일의 CRC32를 고정하는 테스트를 추가했다 — 적용된 파일이 한 글자라도 바뀌면 CI에서 먼저 깨진다
• 새 마이그레이션을 추가할 때만 그 표에 줄을 늘린다. 기존 값을 고쳐야 한다면 그건 파일을 잘못 건드린 것이라는 신호다
• flyway repair로 덮지 않았다 — 공유 DB에 쓰기가 들어가고, "적용본과 파일이 다르다"는 사실만 감춘다. 되돌리는 게 정공법이다

결과

• 적용된 마이그레이션 수정이 배포 전 CI에서 막힐다