# Vì sao file SQL đã chạy ở môi trường khách thì không được sửa nữa

> Flyway, Rails và Liquibase đều lưu dấu từng migration, và cách sửa đúng luôn là viết thêm file mới.

Bản gốc: https://fdetimes.net/vi/cong-cu/flyway-quan-ly-migration-database-khach/

Chỉ cần đổi một chữ `int` thành `bigint` trong file migration đã chạy là Flyway có thể dừng cả pipeline. Công cụ không hề khó tính vô cớ. Nó đang báo cho bạn biết database của khách và file trong repo đã kể hai câu chuyện khác nhau.

Bạn mang tính năng mới đến khách, tính năng đó cần thêm cột hoặc thêm bảng. Cùng một thay đổi phải chạy được ở máy bạn, ở môi trường test và ở database của khách, nơi có khi bạn chỉ được truy cập vài giờ.

Flyway là sản phẩm của Redgate, được hãng giới thiệu là giải pháp quản lý thay đổi database. Phần lõi là mã nguồn mở theo giấy phép Apache 2.0, do Redgate duy trì cùng nhiều contributor. Hiểu vì sao Flyway cấm sửa file cũ cũng là hiểu cách nó giữ cho các môi trường không lệch nhau.

## Mỗi file là một version, và version không được trùng

Versioned migration được đặt tên theo một quy ước mà tài liệu Flyway minh họa bằng ví dụ `V001.002__NewTwitterColumn.sql`: chữ V, số version, hai dấu gạch dưới, rồi đến phần mô tả. Mỗi versioned migration phải có một version riêng.

Khi bạn chạy migrate, Flyway áp trước các versioned migration còn đang chờ, theo thứ tự version, rồi mới đến những repeatable migration đã thay đổi. Thư mục cho hệ thống đơn hàng của một công ty logistics có thể trông như sau:

```
sql/
  V001__create_orders.sql
  V002__add_weight_column.sql
  V003__add_delivery_window.sql
```

Giả sử database của khách đã chạy đến V002 và bạn mang đến V003, thì chỉ V003 là chưa chạy. Ví dụ trong tài liệu dùng số có các chữ số 0 ở đầu. Bạn nên giữ cách đánh số đó ngay từ ngày đầu, để người mở thư mục ra đọc cũng thấy đúng thứ tự.

## Checksum nhớ những gì đã chạy

Mỗi khi thực thi một migration, Flyway lưu lại checksum của nó, với file SQL là CRC32. Bảng schema history trong database đích ghi lại các migration đã áp cùng checksum của từng file. Lệnh validate sẽ báo lỗi nếu tên, loại hoặc checksum của migration khác với những gì đã áp.

Giờ hãy quay lại tình huống mở bài. V002 tạo cột `weight` kiểu `int` và đã chạy trên staging của khách. Một kỹ sư thấy cột cần kiểu `bigint`, mở thẳng V002 ra sửa rồi commit.

Lúc này staging vẫn có cột `int`, còn database nào dựng mới từ repo sẽ có `bigint`. Không ai thấy hai database đã lệch nhau cho đến khi validate chạy và báo checksum của versioned migration không khớp với bản ghi trong schema history. Lỗi đó chặn bạn lại trước khi sự lệch nhau lọt vào production.

## Cách sửa đúng: khôi phục file gốc rồi viết tiếp

Tài liệu Flyway coi việc không sửa migration đã áp là best practice, và khuyên dùng một migration mới để roll forward. Trong ví dụ trên, bạn trả V002 về đúng nội dung gốc, rồi thêm file `V004__widen_weight_to_bigint.sql` chứa câu ALTER đổi kiểu cột.

Từ đó mọi môi trường đều đi qua cùng các bước. Staging chỉ chạy thêm V004. Database mới chạy V002 bản gốc, rồi lần lượt đến V004, nên kết quả cuối cùng giống nhau và lịch sử ghi đúng những gì đã xảy ra.

**Điểm mấu chốt:** Migration đã chạy là lịch sử. Muốn thay đổi thì viết một migration mới.

## Không chỉ Flyway làm vậy

Nguyên tắc này không phải thói quen riêng của một công cụ. Rails theo dõi những migration đã chạy qua bảng `schema_migrations`, nên một file đã chạy mà bị sửa sẽ không được chạy lại. Vì thế hướng dẫn của Rails khuyên viết migration mới thay vì sửa file đã commit.

Liquibase thì mỗi lần chạy hoặc kiểm tra một changeset lại tính lại checksum của nó, rồi so với giá trị đã lưu. Cách sửa Liquibase đề xuất gần như trùng với ví dụ trên: khôi phục changeset gốc, rồi thêm một changeset mới để đổi cột từ int sang bigint.

Vậy nên ở bất kỳ dự án nào của khách, dù dùng stack gì, ngay tuần đầu bạn nên hỏi hai câu. Công cụ migration ở đây lưu lịch sử vào bảng nào, và nó có so checksum không?

## Checksum không bắt được những gì?

Checksum chỉ bảo vệ các file. Nếu ai đó phía khách mở SQL client và thêm một index bằng tay, không file nào thay đổi nên validate không có gì để báo.

Đó là chỗ báo cáo drift có ích. Tutorial Flyway Check với SQL Server dùng tùy chọn `-drift` để tạo một báo cáo liệt kê những đối tượng trong schema không do migration đã áp nào tạo ra.

Thử hình dung bạn chạy báo cáo này trên staging của khách lúc bắt đầu một đợt làm việc: nếu cái index thêm tay kia hiện ra, bạn hỏi người phụ trách database xem nó có cần giữ không, rồi đưa nó vào một migration mới để repo và database lại khớp nhau.

Còn một giới hạn nữa: thứ tự đúng không biến một câu SQL tồi thành an toàn. Migration khóa một bảng lớn trong giờ cao điểm thì vẫn khóa bảng đó, dù nó có version đàng hoàng. Viết migration chạy được trên dữ liệu thật của khách vẫn là việc của bạn.

## Học gì trước, ghi gì vào CV

Bạn nên học theo thứ tự này: quy ước đặt tên, cách migrate chọn ra những file còn chờ, rồi đọc bảng schema history. Học validate và báo cáo drift sau cùng, vì chỉ khi hiểu công cụ lưu những gì thì bạn mới đọc đúng lỗi của nó.

Trong CV, đừng chỉ ghi "biết Flyway".

Khi tin tuyển có nhắc đến database của khách, hãy chuẩn bị sẵn một câu chuyện như vậy cho buổi phỏng vấn.

Bạn sẽ không phải người cuối cùng động vào database của khách. Một chuỗi migration không ai sửa lén là thứ đáng tin nhất bạn để lại cho người đến sau.

**Thử ngay tuần này:**

- Tạo ba file V001, V002, V003 trên một database thử, chạy migrate rồi mở bảng schema history ra xem từng dòng
- Sửa một dòng trong V002 sau khi nó đã chạy, rồi chạy validate để xem lỗi checksum mismatch trông như thế nào
- Khôi phục V002 về bản gốc, viết V004 chứa thay đổi bạn muốn, rồi chạy validate và migrate lại

## Nguồn

- [Flyway - Redgate](https://www.red-gate.com/products/flyway/)

- [flyway/flyway: Flyway by Redgate • Database Migrations Made Easy](https://github.com/flyway/flyway)

- [Versioned migrations - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/versioned-migrations-273973333.html)

- [Migrations - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/migrations-271585107.html)

- [Validate - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/flyway/reference/commands/validate)

- [Flyway schema history table - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)

- [Tutorial - Using Flyway Check with SQL Server - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/tutorial-using-flyway-check-with-sql-server-277579354.html)

- [Active Record Migrations — Ruby on Rails Guides](https://guides.rubyonrails.org/active_record_migrations.html)

- [What affects changeset checksums](https://www.liquibase.com/blog/what-affects-changeset-checksums)
