CDC / Debezium

1. Tổng quan

Change Data Capture (CDC) giữ cho chỉ mục tìm kiếm Typesense đồng bộ với PostgreSQL. Debezium giám sát WAL (Write-Ahead Log) của PostgreSQL và publish các thay đổi mức hàng lên các Kafka topic. Dịch vụ Search consume các sự kiện này, biến đổi chúng và upsert/delete các tài liệu trong Typesense.

PostgreSQL (WAL) → Debezium → Kafka → Search Service → Typesense

2. Kiến trúc

3. Danh mục Topic CDC

Tất cả topic tuân theo quy ước đặt tên Debezium: {prefix}.{schema}.{table}

Kafka Topic	Bảng PostgreSQL	Collection Typesense	Ghi chú
nx.seller.public.Organizer	public.Organizer	organizers
nx.seller.public.Merchant	public.Merchant	merchants
nx.seller.public.Category	public.Category	categories
nx.seller.public.Device	public.Device	devices
nx.seller.public.SaleChannel	public.SaleChannel	sale-channels
nx.seller.public.Product	public.Product	products
nx.seller.public.ProductInfo	public.ProductInfo	products	Chỉ cập nhật một phần

Tiền tố Topic: nx.seller (cấu hình trong Debezium connector)

4. Cấu trúc Payload Debezium

4.1. Định dạng Envelope

{
  "before": { ... },
  "after": { ... },
  "op": "c",
  "ts_ms": 1711785600000,
  "source": {
    "version": "2.x",
    "connector": "postgresql",
    "name": "nx.seller",
    "ts_ms": 1711785600000,
    "snapshot": "false",
    "db": "nx_seller",
    "schema": "public",
    "table": "Product"
  }
}

4.2. Loại Thao tác

Mã	Thao tác	before	after	Hành động
c	Create	null	dữ liệu hàng	Upsert tài liệu
u	Update	dữ liệu cũ	dữ liệu mới	Upsert tài liệu
d	Delete	dữ liệu cũ	null	Xóa tài liệu
r	Snapshot (read)	null	dữ liệu hàng	Upsert tài liệu

5. Pipeline Xử lý

5.1. Cấu hình Consumer

Cài đặt	Giá trị
Consumer ID	cdc-consumer
Auto-commit	false (quản lý offset thủ công)
Max Wait Time	500ms
Max Bytes	5MB
Fallback Mode	earliest

5.2. Batching

Các message được buffer và flush theo batch để các thao tác Typesense hiệu quả:

Cài đặt	Giá trị
Max Batch Size	200 message
Flush Interval	2000ms

5.3. Luồng Xử lý

6. Entity Registry

Dịch vụ CDC dùng pattern registry có thể mở rộng để ánh xạ các bảng database sang collection Typesense:

Bảng	Collection	Transform	Hành vi đặc biệt
Organizer	organizers	Ánh xạ tài liệu đầy đủ	—
Merchant	merchants	Ánh xạ tài liệu đầy đủ	—
Category	categories	Ánh xạ tài liệu đầy đủ	—
Device	devices	Ánh xạ tài liệu đầy đủ	—
SaleChannel	sale-channels	Ánh xạ tài liệu đầy đủ	—
Product	products	Ánh xạ tài liệu đầy đủ	—
ProductInfo	products	Chỉ cập nhật một phần	Bỏ qua delete (xem dưới)

6.1. Trường hợp Đặc biệt ProductInfo

Hàng ProductInfo là dữ liệu bổ sung cho tài liệu Product. Khi một hàng ProductInfo bị xóa, tài liệu Product cha KHÔNG nên bị xóa khỏi chỉ mục tìm kiếm. Do đó:

• Các thao tác Create/Update/Snapshot kích hoạt cập nhật một phần cho tài liệu Product cha
• Thao tác Delete trên ProductInfo bị cố ý bỏ qua

7. Dead Letter Queue (DLQ)

Các message thất bại được gửi đến topic DLQ để điều tra:

Cài đặt	Giá trị
DLQ Topic	nx.seller.cdc.dlq

Các message DLQ bao gồm:

• Payload Debezium gốc
• Thông báo lỗi và stack trace
• Topic và partition nguồn
• Timestamp lỗi

8. Thêm Entity CDC Mới

Để thêm bảng mới vào đồng bộ CDC:

1. Debezium Connector — Thêm bảng vào table.include.list của connector
2. Topic CDC — Định nghĩa tên topic mới trong các hằng số @nx/search
3. Collection Typesense — Tạo schema collection trong SearchCollections
4. Entity Registry — Thêm mục mới vào CDC_ENTITY_REGISTRY với tên collection và hàm transform
5. Consumer — Thêm topic vào danh sách subscription của consumer

9. Xử lý Trường i18n

Typesense không hỗ trợ object JSON lồng nhau một cách native. Đối với các trường i18n (ví dụ { en: "Coffee", vi: "Cà phê" }), transform CDC làm phẳng chúng thành các trường riêng:

name: { en: "Coffee", vi: "Ca phe" }
  → name_en: "Coffee"
  → name_vi: "Ca phe"

Điều này cho phép tìm kiếm và lọc theo ngôn ngữ trong Typesense.

10. Tài liệu Liên quan

Tài liệu	Mô tả
Kiến trúc Kafka	Topic Kafka và consumer group
Search Service	Tích hợp Typesense
Data Layer	Cài đặt PostgreSQL và Typesense