Flyway checksum mismatch — deploy kẹt vì sửa migration đã apply
Ứng dụng fail ngay khi khởi động vì Flyway báo checksum của một migration không khớp với bản đã ghi trong DB, khiến đợt deploy bị kẹt hoàn toàn. Nguyên nhân là có người sửa trực tiếp file migration đã được apply ở staging.
Module 03Module 12
Bối cảnh Nova Loyalty
Nova Loyalty có 5 datasource gồm core, gift, report, legacy, audit, mỗi datasource có bộ migration Flyway riêng chạy trong pipeline triển khai. Schema của core chứa bảng ví, bảng giao dịch điểm với idempotency key và bảng Outbox phục vụ luồng Outbox → Debezium → Kafka. Trong kịch bản này, một thay đổi nhỏ trong migration của core ở staging khiến mọi lần deploy tiếp theo đều chết ở bước khởi động.
Triệu chứng
- Ứng dụng fail start với lỗi Flyway dạng rút gọn:
Validate failed: checksum mismatch for migration version ... - Deploy kẹt hoàn toàn: image mới không lên được ở môi trường gặp lỗi trong khi môi trường khác vẫn chạy bình thường
- Cùng một commit chạy tốt ở môi trường dev nhưng chết ở staging, tạo cảm giác lỗi do môi trường
- Đội ngũ không dám khởi động lại pod cũ vì sợ chạm vào cùng lỗi validation khi app lên lại
Điều tra
- Truy vấn bảng
flyway_schema_historyđể lấy checksum đã lưu cho version bị báo lỗi và đối chiếu với checksum của file migration hiện tại trong repo - Xem lịch sử git của đúng file migration đó để xác nhận file đã bị sửa sau khi được apply, và sửa ở điểm nào
- Phân biệt từng môi trường đã apply version nào: môi trường nào đang giữ checksum cũ, môi trường nào chưa hề apply version này
- Đọc nội dung diff của file để đánh giá thay đổi là tương đương về mặt schema (ví dụ chỉ đổi comment hoặc format) hay đã đổi thật cấu trúc DB
Root cause
Một file migration dạng V... đã được apply ở staging bị sửa trực tiếp thay vì tạo migration mới. Flyway lưu checksum của bản đã apply trong flyway_schema_history và validation ở lần chạy sau phát hiện file hiện tại không còn khớp, nên nó chặn khởi động để bảo vệ tính toàn vẹn của lịch sử schema. Đây là cơ chế bảo vệ hoạt động đúng, không phải lỗi của Flyway.
Fix
- Nếu diff được xác nhận là tương đương về schema, chạy
flyway repairđể đồng bộ lại checksum đã lưu với file hiện tại, sau khi đã ghi lại quyết định và lý do - Nếu file gốc đã đổi thật schema, khôi phục file migration về nguyên bản đã apply và tạo một migration mới chứa thay đổi mong muốn
- Tuyệt đối không sửa tay checksum trong bảng
flyway_schema_historykhi chưa hiểu rõ chênh lệch, vì việc đó che giấu sai khác thật giữa các môi trường
Phòng ngừa
- Thêm bước kiểm tra trong CI để chặn mọi thay đổi lên file migration đã merge vào nhánh chính, buộc thay đổi schema phải đi qua file mới
- Thống nhất quy ước migration bất biến sau khi merge kèm quy ước đặt tên có 14 chữ số (timestamp) để tránh trùng version giữa các nhánh
- Chạy Flyway validate trong pipeline trước khi deploy để lỗi checksum bộc lộ ở CI thay vì ở bước khởi động production
- Ghi rõ quy trình xử lý checksum mismatch vào runbook, trong đó repair chỉ được dùng sau khi đã đối chiếu diff