Tạo source connector PostgreSQL
Đẩy mọi thay đổi trên từng dòng của bảng PostgreSQL vào Kafka topic, để sink connector chuyển tiếp sang hệ thống khác. Connector đọc write-ahead log (WAL) qua logical replication với plugin pgoutput.
Điều kiện cần
- CDC Service ở trạng thái Healthy. Xem Tạo CDC Service.
- Quyền superuser trên server PostgreSQL primary. CDC chạy trên primary, không chạy trên replica hot standby hay warm standby.
- Cơ sở dữ liệu đã chuẩn bị sẵn cho CDC, theo Chuẩn bị cơ sở dữ liệu PostgreSQL.
Chuẩn bị cơ sở dữ liệu PostgreSQL
Chạy các câu lệnh sau trên server primary với quyền superuser.
-
Kiểm tra
wal_level, rồi đặt thànhlogicalnếu đang là giá trị khác.SHOW wal_level;ALTER SYSTEM SET wal_level = 'logical'; -
Khởi động lại service PostgreSQL để
wal_levelmới có hiệu lực. Bỏ qua bước này nếuwal_levelvốn đã làlogical.cảnh báoKhởi động lại server primary sẽ làm gián đoạn các ứng dụng đang dùng cơ sở dữ liệu. Lên lịch khởi động lại vào khung giờ bảo trì.
-
Tạo user có role
REPLICATIONđể connector dùng khi kết nối. Bạn cũng có thể dùng superuser có sẵn.CREATE USER YOUR_USER WITH REPLICATION LOGIN PASSWORD 'YOUR_PASSWORD';Để kiểm tra một user đã tồn tại có quyền superuser không, chạy
SELECT rolsuper FROM pg_roles WHERE rolname = 'YOUR_USER';. -
Tạo publication cho các bảng cần ghi nhận thay đổi nếu user của connector không phải superuser. Đặt tên chỉ gồm chữ thường và chữ số, vì trường Publication name không nhận ký tự nào khác.
-- All tablesCREATE PUBLICATION YOUR_PUBLICATION FOR ALL TABLES;-- Or only some tablesCREATE PUBLICATION YOUR_PUBLICATION FOR TABLE YOUR_SCHEMA.YOUR_TABLE, YOUR_SCHEMA.OTHER_TABLE;Superuser có thể bỏ qua bước này. Khi đó connector tự tạo publication cho mọi bảng, với tên bạn nhập ở Publication name.
-
Cấp quyền
SELECTtrên các bảng cần ghi nhận cho user của connector. Bỏ qua bước này nếu user là superuser.GRANT SELECT ON TABLE YOUR_SCHEMA.YOUR_TABLE TO YOUR_USER;Để cấp quyền
SELECTtrên mọi bảng trong một schema, chạy:DO $$DECLAREtable_record RECORD;BEGINFOR table_record INSELECT table_nameFROM information_schema.tablesWHERE table_schema = 'YOUR_SCHEMA' AND table_type = 'BASE TABLE'LOOPEXECUTE 'GRANT SELECT ON TABLE YOUR_SCHEMA."' || table_record.table_name || '" TO YOUR_USER';END LOOP;END $$; -
Cấp cho user quyền tạo và ghi vào bảng signal
public.cdc_signalnếu bạn định chọn Enable incremental snapshot. Khi bạn tạo connector, hệ thống tạo bảng này, và snapshot chạy thông qua bảng này.GRANT USAGE, CREATE ON SCHEMA public TO YOUR_USER;-- If public.cdc_signal already exists, for example from another connectorGRANT INSERT ON public.cdc_signal TO YOUR_USER;Nếu publication liệt kê từng bảng, thêm
public.cdc_signalvào publication sau khi tạo connector. Xem Thay đổi danh sách bảng trong publication. -
Đặt
REPLICA IDENTITY FULLcho từng bảng cần ghi nhận, để sự kiện thay đổi chứa giá trị của dòng trước và sau khi thay đổi.ALTER TABLE YOUR_SCHEMA.YOUR_TABLE REPLICA IDENTITY FULL;Để áp dụng cho mọi bảng trong một schema, chạy:
DO $$DECLAREtable_record RECORD;BEGINFOR table_record INSELECT table_nameFROM information_schema.tablesWHERE table_schema = 'YOUR_SCHEMA' AND table_type = 'BASE TABLE'LOOPEXECUTE 'ALTER TABLE YOUR_SCHEMA."' || table_record.table_name || '" REPLICA IDENTITY FULL';END LOOP;END $$; -
Tạo bảng heartbeat. Connector ghi heartbeat vào bảng này mỗi khi Heartbeat interval (ms) lớn hơn
0. Giá trị mặc định là0, tức là không gửi heartbeat.CREATE TABLE IF NOT EXISTS public.cdc_heartbeat (id integer PRIMARY KEY,last_heartbeat timestamptz NOT NULL); -
Kiểm tra server còn đủ chỗ cho một replication slot nữa. Connector tạo slot theo tên bạn nhập ở Slot name, hoặc dùng lại slot có sẵn trùng tên.
SHOW max_replication_slots;SELECT slot_name, plugin, slot_type, database, active FROM pg_replication_slots;Để giải phóng slot không còn hoạt động, chạy
SELECT pg_drop_replication_slot('YOUR_SLOT');. Để tăng giới hạn, sửamax_replication_slotstrongpostgresql.conf.
Thay đổi danh sách bảng trong publication
Nếu bạn tạo publication cho một danh sách bảng, chạy các câu lệnh sau với quyền superuser mỗi khi cần thêm hoặc bớt bảng được ghi nhận.
-- List the publications
SELECT * FROM pg_publication;
-- Add tables
ALTER PUBLICATION YOUR_PUBLICATION ADD TABLE YOUR_SCHEMA.YOUR_TABLE;
-- Remove tables
ALTER PUBLICATION YOUR_PUBLICATION DROP TABLE YOUR_SCHEMA.YOUR_TABLE;
Tạo connector
-
Chọn Data platform → Workspace management, rồi chọn workspace.
-
Ở tab Overview, trong phần Services, chọn thẻ CDC.
-
Chọn tab Connectors, rồi chọn Create Connector.

-
Ở màn hình Connector Information, nhập Name, chọn source ở Type và chọn PostgreSQL ở Database.

-
Chọn Next Step. Ở màn hình Properties, nhập thông tin kết nối, Topic prefix, tên slot và tên publication, rồi chọn Test connection. Next Step chỉ khả dụng sau khi kiểm tra thành công và hiển thị thông báo "Connect Successfully".



-
Chọn Next Step. Ở màn hình Additional properties, chọn Mode của snapshot, thêm các bảng cần ghi nhận và đặt Heartbeat interval (ms).


-
Chọn Next Step và kiểm tra cấu hình ở màn hình Review.

-
Chọn Create.
Portal hiển thị "Create Successfully" và mở tab Essential Information của CDC Service. Ở tab Connectors, connector mới có trạng thái Running, và mọi bộ đếm Tasks đều bằng
0cho tới khi task của connector khởi động. Việc này có thể mất tới khoảng 2,5 phút. Snapshot Status hiển thị Not Started cho tới khi bạn chạy incremental snapshot.
Cài đặt của connector
Màn hình Connector Information
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| Name | Có | Tên connector, gồm chữ thường, chữ số và dấu gạch ngang (-). Nếu có chữ hoa, _, . hoặc khoảng trắng, form báo lỗi "Name has invalid characters". |
| Type | Có | Chọn source. |
| Database | Có | Chọn PostgreSQL. |
Màn hình Properties
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| From FPT Database Engine / Manual configuration | Có | Chọn một instance PostgreSQL từ FPT Database Engine, hoặc tự nhập thông tin kết nối. Mặc định chọn Manual configuration. Xem Chế độ kết nối. |
| Database Name | Khi chọn From FPT Database Engine | Instance PostgreSQL trong FPT Database Engine. Danh sách có cả các instance do Lakehouse tạo. Khi bạn chọn một instance, form tự điền Host name và Port. Bạn vẫn sửa được hai trường này. Database, Username và Password vẫn để trống. |
| Host name | Có | Host name hoặc địa chỉ IP của server PostgreSQL. |
| Port | Có | Port của server PostgreSQL, ví dụ 5432. Ở chế độ Manual configuration, trường này không có giá trị mặc định. |
| Database | Có | Cơ sở dữ liệu cần ghi nhận thay đổi. |
| Username | Có | User bạn đã chuẩn bị ở bước 3. |
| Password | Có | Mật khẩu của user. |
| Enable incremental snapshot | Không | Cho phép chạy incremental snapshot trên connector này. Khi chọn, việc tạo connector tạo thêm bảng signal public.cdc_signal, và Test connection kiểm tra quyền CREATE TABLE và INSERT. Bảng signal cũng có một topic riêng, TOPIC_PREFIX.public.cdc_signal. Nếu không chọn, sẽ không có bảng signal, nên Snapshot → Execute không chạy được dù menu vẫn hiển thị. Xem Incremental snapshot. |
| Topic prefix | Có | Prefix của các Kafka topic mà connector ghi vào. Mỗi bảng có một topic TOPIC_PREFIX.SCHEMA.TABLE, ví dụ syncdata.inventory.customer. Xem Topic prefix. |
| Slot name | Có | Replication slot mà connector dùng để đọc dữ liệu. Chỉ gồm chữ thường và chữ số. Nếu có ký tự khác, ví dụ _, form báo lỗi "Slot name has invalid characters". Connector tự tạo slot, hoặc dùng lại slot có sẵn trùng tên. |
| Publication name | Có | Publication bạn đã tạo ở bước 4. Với superuser, đây là tên publication mà connector tự tạo. Chỉ gồm chữ thường và chữ số. Nếu có ký tự khác, ví dụ _, form báo lỗi "Publication name has invalid characters". |
Màn hình Additional properties
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| Mode | Có | Cách connector xử lý các dòng đã có. Trường này không có giá trị mặc định, nên bạn cần chọn một chế độ. initial tạo snapshot các dòng này, rồi ghi nhận thay đổi. initial_only chỉ tạo snapshot, không ghi nhận thay đổi. no_data chỉ ghi nhận thay đổi mới. Xem Chế độ snapshot. |
| Include | Không | Các bảng cần ghi nhận. Chọn + để tải danh sách schema và bảng của cơ sở dữ liệu, rồi chọn tối đa 100 bảng. Dùng Filter để tìm trong danh sách và biểu tượng xóa để bỏ một bảng. Nếu không thêm bảng nào, connector ghi nhận mọi bảng. |
| Heartbeat interval (ms) | Có | Khoảng thời gian giữa hai message heartbeat, từ 0 đến 30000. Mặc định 0, tức là không gửi heartbeat. Connector ghi heartbeat vào bảng ở bước 8. Xem Heartbeat. |
Dọn dẹp sau khi xóa connector
Khi bạn xóa source connector PostgreSQL, replication slot và publication của connector vẫn còn trong cơ sở dữ liệu.
Chừng nào chưa xóa replication slot, PostgreSQL còn giữ toàn bộ WAL mà slot chưa đọc, nên dung lượng đĩa tiếp tục tăng.
Xóa slot và publication với quyền superuser.
SELECT pg_drop_replication_slot('YOUR_SLOT');
DROP PUBLICATION YOUR_PUBLICATION;