ADR-0003. Phát hiện schema lệch nhưng không bao giờ tự dựng lại collection

Field	Value
Status	Accepted
Date	2026-03-01
Deciders	Phat Nguyen
Supersedes	-

Bối cảnh

• Khi khởi động, TypesenseSearchEngineComponent so sánh cấu hình của từng collection đã đăng ký với collection Typesense đang chạy.
• Typesense không thể thay đổi tại chỗ phần lớn các định nghĩa trường; áp dụng một schema đã đổi thường đồng nghĩa với việc phải xoá rồi tạo lại collection.
• Tạo lại một collection sẽ xoá toàn bộ document của nó, tức là âm thầm xoá sạch search index trong một lần deploy thông thường.
• Reindex lại từ CDC/nguồn sau khi xoá có thể mất rất lâu và để lại một khoảng thời gian kết quả rỗng hoặc thiếu.

Quyết định

Chúng tôi sẽ tạo collection nếu nó chưa tồn tại, nhưng khi phát hiện lệch nhau thì chỉ ghi log một error ("manual migration required") và để nguyên collection đang chạy. Các thay đổi trường mang tính bổ sung được triển khai qua script migrate:apply tường minh (PATCH schema chỉ-thêm lên collection đang chạy); các thay đổi phá vỡ đi qua luồng dựng lại blue-green migrate:rebuild - một thao tác cố ý, do con người thực hiện.

Hệ quả

Ưu	Nhược
Một lần deploy không bao giờ âm thầm xoá sạch index	Thay đổi schema cần một bước thủ công + sự lưu ý của operator
Operator tự chọn khoảng thời gian reindex an toàn	Cấu hình và schema đang chạy có thể lệch nhau cho tới khi được xử lý
Script backfill xử lý trường hợp bổ sung thường gặp	Các thay đổi phá huỷ mới cần một bước runbook được ghi lại

Các phương án đã cân nhắc

Phương án	Ưu	Nhược	Lý do loại bỏ
Tự xoá + tạo lại khi lệch nhau	Hoàn toàn tự động	Xoá sạch document mỗi lần deploy có đổi schema	Rủi ro mất dữ liệu không thể chấp nhận
Chặn khởi động khi lệch nhau	Buộc phải xử lý	Hạ cả service chủ chỉ vì một khác biệt schema của search	Quá thô bạo; search không nằm trên đường tới hạn
Đổi alias theo version (collection blue/green)	Reindex không gián đoạn	Nhiều thành phần biến động hơn, phải quản lý alias	Hoãn lại - quá mức cần thiết cho quy mô hiện tại

Tham chiếu

• packages/search/src/components/typesense-search-engine.component.ts - ensureCollectionsWithMigration
• packages/search/src/helpers/schema-migration.helper.ts
• Operations