Cài đặt chung của connector
Dùng trang này để tra cứu các cài đặt xuất hiện trên form của nhiều connector, như chế độ kết nối, topic hay error tolerance. Trang của từng connector dẫn link tới đây cho các cài đặt này, và mô tả đầy đủ các trường riêng của connector đó.
Tra cứu nhanh
| Cài đặt | Màn hình | Connector |
|---|---|---|
| Tên | Connector Information | Mọi connector |
| Chế độ kết nối | Properties | Connector cơ sở dữ liệu, source connector Kafka và Kafka MM2 |
| Topic prefix | Properties | Source connector, trừ Kafka và S3 |
| Topic | Properties | Sink connector |
| Incremental snapshot | Properties | Source connector MySQL, MariaDB và PostgreSQL |
| Converter | Properties | Sink connector |
| Chế độ snapshot | Additional properties | Source connector PostgreSQL, MySQL, MariaDB, SQL Server, Oracle và MongoDB |
| Heartbeat | Additional properties | Source connector PostgreSQL, MySQL, MariaDB và SQL Server |
| Tasks max | Additional properties | Sink connector, source connector Kafka và Kafka MM2 |
| Map table | Additional properties | Sink connector, trừ S3 và Redis |
| Error tolerance | Additional properties | Sink connector trừ MongoDB, cùng source connector MongoDB và S3 |
| Múi giờ | Additional properties | Sink connector PostgreSQL, MySQL, MariaDB, SQL Server và S3 |
Form hầu như không đánh dấu * cho trường nào, nên trường không có dấu này vẫn có thể là trường bắt buộc. Khi bạn để trống một trường bắt buộc, form báo ngay dưới trường đó, ví dụ "Name is required". Chỉ Heartbeat interval (ms) của source connector có dấu * màu đỏ.
Màn hình Review ở cuối form tạo connector không hiển thị chế độ kết nối, Database Name, Converter class, Timezone, cũng như công tắc Create new hoặc Create new table.
Màn hình Connector Information
Tên
Màn hình đầu tiên của form tạo connector là Connector Information, chỉ gồm một phần Basic Information. Phần này yêu cầu nhập Name, Type (source hoặc sink) và Database của connector. Database chỉ chọn được sau khi bạn chọn Type.
Name chỉ chấp nhận chữ thường, số và dấu gạch ngang (-). Nếu tên có chữ hoa, dấu gạch dưới (_), dấu chấm (.) hoặc khoảng trắng, form báo "Name has invalid characters", dù dòng gợi ý dưới trường ghi "Only letters, numbers, hyphens are allowed". Nếu để trống tên, form báo "Name is required".
Màn hình Properties
Chế độ kết nối
Trong phần Database Information, phần lớn connector cơ sở dữ liệu cho bạn chọn cách kết nối tới cơ sở dữ liệu. Lựa chọn mặc định là Manual configuration.
- From FPT Database Engine: chọn instance ở Database Name. Portal tự điền Host name và Port, bạn vẫn sửa được hai trường này. Sau đó điền các trường còn lại.
- Manual configuration: nhập các trường kết nối của bất kỳ cơ sở dữ liệu nào mà workspace truy cập được. Port không có giá trị mặc định, nên bạn cần tự nhập.
| Trường | Mô tả |
|---|---|
| Database Name | Chỉ có khi dùng From FPT Database Engine. Danh sách hiển thị các instance FPT Database Engine thuộc engine tương ứng trong tenant. Mỗi mục chỉ hiển thị tên instance, và hai instance có thể trùng tên. |
| Host name | Tên host hoặc địa chỉ IP của máy chủ cơ sở dữ liệu. |
| Port | Port của máy chủ cơ sở dữ liệu, ví dụ 3306 cho MySQL. |
| Database | Với source connector, cơ sở dữ liệu cần ghi nhận thay đổi. Với sink connector, cơ sở dữ liệu để ghi dữ liệu vào. |
| Username | User cơ sở dữ liệu mà connector dùng. Trang của từng source connector liệt kê các quyền user này cần. |
| Password | Mật khẩu của user đó. |
Connector MongoDB dùng Connection URL, còn sink OpenSearch dùng Connection string, thay cho host và port. Khi dùng From FPT Database Engine, portal tự điền trường này và bạn không sửa được. Source connector Kafka và Kafka MM2 cũng dùng hai lựa chọn này cho Kafka cluster mà chúng đọc dữ liệu. Với Kafka MM2, lựa chọn mặc định là From FPT Database Engine. Trên source connector Oracle, From FPT Database Engine bị mờ, nên bạn dùng Manual configuration. Các connector kết nối qua URL hoặc endpoint, như Elasticsearch, Redis, Iceberg và S3, không có lựa chọn này.
Sau khi điền các trường kết nối, chọn Test connection. Portal kiểm tra kết nối từ workspace tới cơ sở dữ liệu bạn đã nhập. Nếu bạn đã chọn Enable incremental snapshot, bước kiểm tra còn xác minh các quyền mà snapshot cần. Xem Incremental snapshot.
Next Step chỉ khả dụng sau khi Test connection thành công với thông báo "Connect Successfully". Nếu còn trường bắt buộc để trống, portal không chạy kiểm tra, và form báo ngay dưới trường đó, ví dụ "Access Key is required". Quy tắc này áp dụng cho màn hình Properties của mọi connector.
Topic prefix
Source connector ghi sự kiện thay đổi của mỗi bảng vào một Kafka topic riêng. Trong phần Kafka topic, Topic prefix là phần đầu của mọi tên topic. Phần còn lại của tên tùy theo nguồn.
| Source connector | Tên topic |
|---|---|
| PostgreSQL, Oracle | TOPIC_PREFIX.SCHEMA.TABLE |
| MySQL, MariaDB | TOPIC_PREFIX.DATABASE.TABLE |
| SQL Server | TOPIC_PREFIX.DATABASE.SCHEMA.TABLE |
| MongoDB | TOPIC_PREFIX.DATABASE.COLLECTION |
Ví dụ, với prefix syncdata, schema inventory và các bảng customer, order, item, connector PostgreSQL ghi vào syncdata.inventory.customer, syncdata.inventory.order và syncdata.inventory.item.
Connector MySQL và MariaDB còn ghi vào một topic chỉ mang tên prefix, ví dụ syncdata. Topic này cũng xuất hiện trong danh sách topic của sink connector.
Trường này bắt buộc và chấp nhận chữ thường, số, dấu gạch ngang (-), dấu gạch dưới (_) và dấu chấm (.). Nếu có chữ hoa, khoảng trắng hoặc ký tự như !, form báo "Topic prefix has invalid characters". Source connector Oracle không kiểm tra ký tự. Sink connector chọn topic cần đọc theo các tên này, nên đặt prefix thể hiện rõ dữ liệu đến từ nguồn nào, và dùng prefix khác nhau cho mỗi source connector. Nếu sau này đổi prefix, connector ghi các thay đổi mới vào topic mang tên mới, nên bạn cần cập nhật các sink đang đọc topic đó. Source connector S3 yêu cầu Topic thay cho trường này, tức tên đầy đủ của topic duy nhất mà connector ghi vào.
Topic
Sink connector đọc các Kafka topic bạn chọn trong phần Kafka topic của màn hình Properties. Danh sách chỉ gồm các topic đã tồn tại: source connector chỉ tạo topic của một bảng khi ghi bản ghi đầu tiên từ bảng đó, nên bảng nguồn chưa có dòng nào thì chưa có topic. Tùy connector, phần này hiển thị một trong hai kiểu chọn topic.
- Danh sách chọn Topics: liệt kê các topic có trong Kafka cluster của CDC Service. Gõ một phần tên để lọc danh sách, rồi chọn các topic cần đọc. Mỗi topic đã chọn hiển thị thành một tag có ×. Kiểu này dùng cho các sink MySQL, MariaDB, SQL Server, OpenSearch, cả hai sink ClickHouse và cả hai sink Iceberg.
- Bảng topic: danh sách Selected topics kèm số đếm Total topic và hai cột Topic, Action. Kiểu này dùng cho các sink PostgreSQL, MongoDB, Elasticsearch, S3 và Redis. Source connector Kafka và Kafka MM2 cũng dùng bảng này cho topic của cluster kia. Với hai loại này, nút + chỉ khả dụng sau khi Test connection thành công.

| Nút trong bảng topic | Chức năng |
|---|---|
| + | Mở panel Select topics. Lọc topic theo tên, chọn checkbox của topic hoặc Select All, rồi chọn Select. |
| × | Xóa toàn bộ danh sách topic. |
| Biểu tượng xóa ở cột Action | Bỏ topic đó khỏi danh sách. |
Bảng topic chứa tối đa 100 topic.
Incremental snapshot
Enable incremental snapshot là checkbox không bắt buộc trong phần Database Information của source connector MySQL, MariaDB và PostgreSQL. Chọn checkbox này để sau này chạy snapshot trong khi connector vẫn truyền thay đổi. Các source connector khác, kể cả SQL Server, không hỗ trợ incremental snapshot.
Khi bạn tạo connector có chọn checkbox này, CDC Service tạo một bảng signal trong cơ sở dữ liệu nguồn: public.cdc_signal trên PostgreSQL, và cdc_signal trong Database mà connector ghi nhận trên MySQL và MariaDB. Menu Snapshot gửi lệnh tới connector thông qua bảng này. Vì vậy user cơ sở dữ liệu cần quyền CREATE TABLE và INSERT, và Test connection kiểm tra các quyền này khi bạn chọn checkbox. Nếu thiếu quyền, kiểm tra thất bại và portal báo lỗi kèm chi tiết. Cấp quyền còn thiếu cho user cơ sở dữ liệu, rồi chọn Test connection lại. Khi kiểm tra thành công, portal hiển thị "Connect Successfully".
Chọn checkbox này ngay khi tạo connector. Nếu không chọn, connector không có bảng signal, nên Execute không bắt đầu được snapshot, dù menu Snapshot vẫn hiển thị.
Bạn bắt đầu và điều khiển snapshot bằng Execute, Pause, Resume và Stop trong menu Snapshot của connector, rồi theo dõi ở cột Snapshot Status của tab Connectors. Xem Chạy incremental snapshot.
Converter
Sink connector có phần Converter trên màn hình Properties, dùng cho key và value của các message mà connector đọc. Chọn Converter class trước: bốn trường còn lại bị mờ cho tới khi bạn chọn. Sau đó các trường này vẫn để trống, nên bạn cần chọn giá trị cho từng trường, kể cả khi danh sách chỉ có một lựa chọn.

| Trường | Mô tả |
|---|---|
| Converter class | Converter class của sink. Mỗi sink chỉ có một class: JDBC cho PostgreSQL, MySQL, MariaDB và SQL Server, MongoDB cho MongoDB, Clickhouse log cho ClickHouse (Logs), Clickhouse replica cho ClickHouse Replicate, Opensearch cho OpenSearch, Elasticsearch cho Elastic Search, S3 cho S3, Iceberg replica cho Iceberg, Iceberg log cho Iceberg (logs) và Redis cho Redis. |
| Converter key | Converter cho key của message. Với JDBC, lựa chọn duy nhất là org.apache.kafka.connect.json.JsonConverter. |
| Converter key schema enable | Key của message có dùng schema hay không. Với JDBC, lựa chọn duy nhất là true. |
| Converter value | Converter cho value của message, ví dụ org.apache.kafka.connect.json.JsonConverter. |
| Converter value schema enable | Value của message có dùng schema hay không, ví dụ true. |
Nếu bạn quay lại và đổi Database, chọn lại Converter class và bốn trường converter. Form có thể vẫn giữ class và các giá trị đã chọn cho cơ sở dữ liệu trước đó, kể cả những giá trị không có trong danh sách mới.
Màn hình Additional properties
Chế độ snapshot
Source connector có thể sao chép dữ liệu đã có trong các bảng trước khi ghi nhận thay đổi mới. Trong phần Snapshot, Mode quyết định hành vi này. Trường này bắt buộc.
| Mode | Hành vi của connector |
|---|---|
| initial | Snapshot toàn bộ dữ liệu có sẵn trong các bảng, rồi tiếp tục ghi nhận thay đổi. |
| initial_only | Chỉ snapshot toàn bộ dữ liệu có sẵn trong các bảng. Không ghi nhận các thay đổi sau đó. |
| no_data | Bỏ qua snapshot, chỉ ghi nhận các thay đổi xảy ra sau khi connector khởi động. |
MySQL và MariaDB xóa binlog cũ sau một thời gian, nên connector của hai hệ này dùng một initial snapshot nhất quán để đảm bảo dữ liệu đầy đủ trước khi đọc binlog.
Source connector MongoDB cũng có Mode trong phần Snapshot, nhưng với các giá trị khác.
| Mode | Hành vi của connector |
|---|---|
| latest | Chỉ ghi nhận các thay đổi xảy ra sau khi connector khởi động. Không sao chép các document có sẵn. |
| copy existing | Sao chép toàn bộ document có sẵn trong khi vẫn ghi nhận thay đổi. Nếu collection thay đổi trong lúc sao chép, connector tạo hai sự kiện cho cùng một document: một sự kiện copyingData và một sự kiện cho thao tác đó (insert, update hoặc delete). |
Để snapshot lại dữ liệu sau khi connector đã chạy, dùng incremental snapshot. Xem Incremental snapshot.
Heartbeat
Source connector PostgreSQL, MySQL, MariaDB và SQL Server gửi heartbeat message. Heartbeat giữ connector hoạt động và cập nhật offset khi các bảng được ghi nhận không có thay đổi dữ liệu. Trên PostgreSQL, heartbeat còn giúp cơ sở dữ liệu giải phóng WAL cũ mà replication slot lẽ ra vẫn giữ lại. Đặt chu kỳ gửi ở Heartbeat interval (ms), trong phần Heartbeat. Trường này bắt buộc.
- Giá trị mặc định:
0trên connector PostgreSQL, MySQL, MariaDB và SQL Server. - Khoảng giá trị:
0đến30000mili giây. 0không gửi heartbeat.1000gửi mỗi giây một lần,5000gửi 5 giây một lần.
Bạn không đổi được chu kỳ sau khi tạo connector. Trang chi tiết hiển thị giá trị này trong phần Heartbeat.
Trên PostgreSQL, heartbeat dùng bảng public.cdc_heartbeat. Tạo bảng này trong cơ sở dữ liệu nguồn trước khi tạo connector. Xem Tạo source connector PostgreSQL.
Tasks max
Phần Task đặt số task tối đa mà connector chạy song song. Tùy connector, trường này có tên Tasks max, Number of tasks hoặc Number of task. Sink PostgreSQL gọi trường này là Number of tasks trên form, nhưng là Tasks max trên màn hình Review và trang chi tiết.
Connector chạy được nhiều task cùng lúc khi topic có nhiều hơn một partition. Khi có nhiều task, connector có thể đọc message không đúng thứ tự. Để giữ đúng thứ tự cho các message liên quan, đảm bảo chúng có cùng message key để cùng vào một partition.
Với source connector Kafka, số task thường nhỏ hơn hoặc bằng số partition của Kafka topic.
Map table
Sink connector ánh xạ mỗi topic tới một bảng, một index hoặc một collection ở hệ thống đích. Tùy connector, phần Map table hiển thị mỗi topic một dòng, hoặc một bảng gồm mọi topic.
| Trường | Mô tả |
|---|---|
| Topic (Topic 1, Topic 2…) | Topic chứa dữ liệu thay đổi từ source connector. |
| Create new hoặc Create new table | Bật: nhập tên bảng mới cần tạo ở hệ thống đích. Tên có thể gồm chữ cái, số và dấu gạch dưới. Tắt: chọn một bảng có sẵn. Create new mặc định bật và portal điền sẵn tên theo topic (PostgreSQL, MongoDB). Create new table mặc định tắt, và khi bạn bật thì ô tên để trống (MySQL, MariaDB, SQL Server, OpenSearch). Nếu tên không hợp lệ, form báo "Table has invalid characters", còn nếu để trống tên, form báo "Table is required". Hai sink ClickHouse không có công tắc này và chỉ nhận bảng có sẵn. |
| Table (Table 1…) hoặc Index | Bảng nhận dữ liệu của topic. Trên sink OpenSearch, Table 1 là tên index đích, còn trên sink Elasticsearch cột này có tên Index. Trên sink MongoDB, cột này cũng có tên Index, nhưng chứa tên collection đích. Màn hình Review và trang chi tiết hiển thị cột này là Collection, và nếu để trống Index, form báo "Table is required". |
| Filter | Tìm trong danh sách theo tên topic hoặc tên bảng. |
| Enable filter errors | Chỉ có trên sink PostgreSQL và MongoDB. Hiển thị riêng các dòng có tên bảng bị lỗi. Errors cho biết số dòng bị lỗi. |
Error tolerance
Trong phần Error Tolerance, Mode quyết định connector làm gì khi gặp message không xử lý được. Trường này bắt buộc.
| Mode | Hành vi của connector |
|---|---|
| None | Connector dừng ở message lỗi đầu tiên và chuyển sang trạng thái Failed. Xử lý nguyên nhân lỗi, rồi khởi động lại connector. |
| All | Bỏ qua các message lỗi và tiếp tục chạy. Sink connector còn ghi các message này vào topic bạn nhập để nhận bản ghi lỗi, trong Kafka cluster của CDC Service. |
All chỉ áp dụng cho các message mà connector không đọc hoặc không chuyển đổi được. Lỗi do hệ thống đích trả về trong lúc connector ghi, ví dụ vi phạm ràng buộc trong cơ sở dữ liệu, vẫn có thể làm connector dừng.
Trên sink connector, phần Error Tolerance hiển thị trường Topic đi kèm All. Nhập topic nhận bản ghi lỗi vào trường này. Source connector MongoDB cũng hiển thị trường Topic này cho các message lỗi. Source connector S3 bỏ qua các bản ghi lỗi mà không ghi chúng vào topic nào.
Múi giờ
Sink connector PostgreSQL, MySQL, MariaDB và SQL Server có phần Database timezone với danh sách Timezone. Chọn múi giờ của dữ liệu trong cơ sở dữ liệu nguồn: UTC hoặc Asia/Ho_Chi_Minh. Danh sách không có giá trị mặc định. Sink S3 hiển thị Timezone trong phần Source, cạnh Database Type.