ADR-0003. Phát hiện schema drift nhưng không bao giờ auto-rebuild collection

Field	Value
Status	Accepted
Date	2026-03-01
Deciders	@search-team
Supersedes	—

Bối cảnh

• Khi bootstrap, TypesenseSearchEngineComponent so sánh từng config collection đã đăng ký với collection Typesense live.
• Typesense không thể alter hầu hết định nghĩa trường tại chỗ; áp dụng một schema đã đổi thường nghĩa là drop và recreate collection.
• Recreate một collection xóa toàn bộ document của nó, sẽ âm thầm wipe search index trong một deploy thường lệ.
• Reindex từ CDC/nguồn sau khi drop có thể mất rất lâu và để lại một cửa sổ kết quả rỗng/partial.

Quyết định

Chúng tôi sẽ tạo một collection nếu nó thiếu, nhưng khi phân kỳ chúng tôi chỉ log một error ("manual migration required") và để collection live nguyên vẹn. Thay đổi trường additive được rollout qua các script backfill rõ ràng (migrate:references, migrate:denorm); recreate phá hủy là một thao tác cố ý, chạy bởi con người.

Hệ quả

Ưu	Nhược
Một deploy không bao giờ âm thầm wipe index	Thay đổi schema cần một bước thủ công + sự nhận biết của operator
Operator chọn cửa sổ reindex an toàn	Config và schema live có thể giữ phân kỳ đến khi được xử lý
Script backfill xử lý case additive thường gặp	Thay đổi phá hủy mới cần một bước runbook tài liệu hóa

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

Phương án	Ưu	Nhược	Lý do loại bỏ
Auto drop + recreate khi phân kỳ	Tự động hoàn toàn	Wipe document mỗi deploy đổi schema	Rủi ro mất dữ liệu không chấp nhận được
Block bootstrap khi phân kỳ	Bắt buộc hành động	Hạ cả host vì một diff schema search	Quá thô; search không nằm trên đường tới hạn
Versioned alias swap (collection blue/green)	Reindex zero-downtime	Nhiều phần biến động hơn, quản lý alias	Hoãn lại — quá mức 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