요약 — DeployHub 서버 기동 로그의 Migration checksum mismatch를 적용된 SQL 파일과 기존 DB 이력의 불일치로 좁혔다. 주석 수정도 검증에 영향을 줄 수 있었지만 매번 빈 DB로 시작하던 테스트에는 기존 이력이 없었다. 파일 변경 감지 테스트를 추가하고, 기존 이력을 가진 DB의 업그레이드 검증과 당시 baseline 절차의 범위를 구분했다.

배경

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

문제 (증상)

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

원인 분석

• Flyway의 적용 이력 검증은 SQL 마이그레이션의 계산된 체크섬을 비교하며 주석 수정도 불일치를 일으킬 수 있다. 이를 파일 바이트 전체의 CRC32와 동일하다고 설명하지 않는다. 인코딩·BOM·줄바꿈 처리의 세부는 사용한 Flyway 버전의 계산 규칙을 확인해야 한다.
• 적용 이력은 DB의 flyway_schema_history에 있고, 파일은 저장소에 있다. 둘이 어긋나는 순간 기동이 막힌다
• 당시 통합 테스트는 Testcontainers의 빈 DB에서 새로 마이그레이션을 적용했다. 과거에 적용한 파일의 체크섬과 비교할 이력이 없어 이번 불일치를 검출하지 못했다. 빈 DB 테스트가 다른 SQL 실행 오류까지 항상 통과한다는 뜻은 아니다.
• 놓친 것은 통합 테스트 전체의 한계가 아니라 기존 DB 이력을 재현하지 않은 테스트 전략의 공백이다. 이전 스키마와 적용 이력을 가진 DB에 다음 버전을 적용하는 업그레이드 테스트는 별도 대안이며, 이번 기록에서 새로 실행한 것으로 주장하지 않는다.

해결

• 당시에는 마이그레이션 통합과 기존 DB의 baseline 전환을 선택했다. 이는 그때의 운영 이관 절차이며 체크섬 불일치의 일반 복구 처방이 아니다. 기존 스키마·이력·데이터의 정합성, 백업과 되돌리기 계획을 확인하지 않고 다른 환경에 적용해서는 안 된다.
• 마이그레이션 파일의 CRC32를 기준값과 비교하는 변경 감지 테스트를 추가했다. 파일 변경을 발견하는 회귀 가드이며 Flyway 자체의 체크섬 계산이나 기존 DB 업그레이드 테스트를 대체하지 않는다.
• 새 마이그레이션을 추가할 때만 그 표에 줄을 늘린다. 기존 값을 고쳐야 한다면 그건 파일을 잘못 건드린 것이라는 신호다
• flyway repair로 덮지 않았다 — 공유 DB에 쓰기가 들어가고, "적용본과 파일이 다르다"는 사실만 감춘다. 되돌리는 게 정공법이다

결과

• 기준값을 고정한 파일의 변경을 배포 전 테스트에서 감지하도록 했다. 이 결과는 파일 변경 가드의 범위이며 운영 DB의 모든 이력·데이터 정합성까지 보장하지 않는다.