Chuyển tới nội dung chính

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​

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.

  1. Kiểm tra wal_level, rồi đặt thành logical nếu đang là giá trị khác.

    SHOW wal_level;
    ALTER SYSTEM SET wal_level = 'logical';
  2. Khởi động lại service PostgreSQL để wal_level mới có hiệu lực. Bỏ qua bước này nếu wal_level vốn đã là logical.

    cảnh báo

    Khở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ì.

  3. 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';.

  4. 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 tables
    CREATE PUBLICATION YOUR_PUBLICATION FOR ALL TABLES;
    -- Or only some tables
    CREATE 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.

  5. Cấp quyền SELECT trê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 SELECT trên mọi bảng trong một schema, chạy:

    DO $$
    DECLARE
    table_record RECORD;
    BEGIN
    FOR table_record IN
    SELECT table_name
    FROM information_schema.tables
    WHERE table_schema = 'YOUR_SCHEMA' AND table_type = 'BASE TABLE'
    LOOP
    EXECUTE 'GRANT SELECT ON TABLE YOUR_SCHEMA."' || table_record.table_name || '" TO YOUR_USER';
    END LOOP;
    END $$;
  6. Cấp cho user quyền tạo và ghi vào bảng signal public.cdc_signal nế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 connector
    GRANT INSERT ON public.cdc_signal TO YOUR_USER;

    Nếu publication liệt kê từng bảng, thêm public.cdc_signal vào publication sau khi tạo connector. Xem Thay đổi danh sách bảng trong publication.

  7. Đặt REPLICA IDENTITY FULL cho 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 $$
    DECLARE
    table_record RECORD;
    BEGIN
    FOR table_record IN
    SELECT table_name
    FROM information_schema.tables
    WHERE table_schema = 'YOUR_SCHEMA' AND table_type = 'BASE TABLE'
    LOOP
    EXECUTE 'ALTER TABLE YOUR_SCHEMA."' || table_record.table_name || '" REPLICA IDENTITY FULL';
    END LOOP;
    END $$;
  8. 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
    );
  9. 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ửa max_replication_slots trong postgresql.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​

  1. Chọn Data platform → Workspace management, rồi chọn workspace.

  2. Ở tab Overview, trong phần Services, chọn thẻ CDC.

  3. Chọn tab Connectors, rồi chọn Create Connector.

    Tab Connectors của CDC Service ở trạng thái Healthy, với thông báo No connector yet và nút Create Connector

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

    Màn hình Connector Information của form Create Connector với các trường Name, Type và Database

  5. 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".

    Phần Database Information khi chọn From FPT Database Engine, gồm danh sách Database Name và các trường kết nối

    Phần Database Information khi chọn Manual configuration, gồm các trường Host name, Port, Database, Username, Password và checkbox Enable incremental snapshot

    Phần Kafka topic với trường Topic prefix

    Phần Replication với các trường Slot name và Publication name

  6. 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).

    Phần Snapshot, Mode đang chọn initial

    Phần Include với nút thêm, nút xóa hết, ô Filter và bốn bảng liệt kê theo Schema, Table và Table path

    Phần Heartbeat, Heartbeat interval (ms) đã nhập 3000

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

    Màn hình Review của source connector PostgreSQL với các phần Basic Information, Kafka topic, Database Information, Snapshot, Include và Heartbeat

  8. 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 0 cho 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ườngBắt buộcMô tả
NameCó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".
TypeCóChọn source.
DatabaseCóChọn PostgreSQL.

Màn hình Properties​

TrườngBắt buộcMô tả
From FPT Database Engine / Manual configurationCó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 NameKhi chọn From FPT Database EngineInstance 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 nameCóHost name hoặc địa chỉ IP của server PostgreSQL.
PortCóPort của server PostgreSQL, ví dụ 5432. Ở chế độ Manual configuration, trường này không có giá trị mặc định.
DatabaseCóCơ sở dữ liệu cần ghi nhận thay đổi.
UsernameCóUser bạn đã chuẩn bị ở bước 3.
PasswordCóMật khẩu của user.
Enable incremental snapshotKhôngCho 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 prefixCó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 nameCó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 nameCó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ườngBắt buộcMô tả
ModeCó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.
IncludeKhôngCá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.

cảnh báo

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;

Bước tiếp theo​