Flyway migration: quy ước đặt tên và best practice

Flyway quản lý thay đổi schema database bằng các file SQL có phiên bản, chạy theo thứ tự và ghi lại đã chạy tới đâu trong bảng flyway_schema_history. Đây là cách chuẩn để schema đi cùng code qua mọi môi trường.

Quy ước đặt tên

• Versioned: V1__create_users.sql, V2__add_email_index.sql — chạy đúng một lần, theo thứ tự phiên bản
• Repeatable: R__refresh_views.sql — chạy lại mỗi khi nội dung đổi (checksum), hợp cho view/function
• Prefix V/R, hai gạch dưới __ ngăn cách phiên bản và mô tả

Quy tắc vàng: không sửa migration đã chạy

Flyway lưu checksum mỗi file. Sửa một migration đã áp dụng sẽ làm lệch checksum và build lỗi ở môi trường khác. Muốn đổi schema? Tạo migration mới để tiến lên, đừng sửa quá khứ.

Best practice

1. Mỗi migration là một thay đổi logic, nhỏ và có thể review
2. Đặt migration vào version control cùng code ứng dụng
3. Tránh dữ liệu phụ thuộc thời gian/ngẫu nhiên trong migration
4. Với PostgreSQL, cân nhắc tách DDL nặng (thêm index) ra để không khoá bảng lâu

Rollback thì sao?

Bản Flyway community không tự rollback. Thực tế nên viết migration tiến tới để sửa (roll-forward): nếu V5 sai, viết V6 để khắc phục, thay vì cố lùi lại.

👉 Dùng thử công cụ liên quan trên dev-hub: SQL Formatter — chạy hoàn toàn trong trình duyệt, không gửi dữ liệu lên server.