03 Managed Postgres CDC

Tài liệu đồng hành của người điều phối cho bài học 03 Managed Postgres CDC.

Thời lượng

Khoảng 20 phút. Một instance managed Postgres nhận kết nối trong khoảng một phút sau clickhousectl cloud postgres create, nên người tham dự có thể cấp phát nó và điền biến môi trường trong lúc bạn thuyết minh về CDC. ClickPipe thường mất vài phút để snapshot và bắt đầu stream, nhưng quá trình kiểm chứng đã thấy việc cấp phát vượt quá 10 phút. Hãy bắt đầu sớm và dùng các bước kiểm tra leo thang trong phần xử lý sự cố của học viên thay vì hứa một thời điểm hoàn tất cố định.

Nội dung dẫn giảng

• Mỗi người tham dự tạo Postgres RIÊNG của họ do ClickHouse quản lý trong tổ chức trial của mình — không có instance dùng chung trên đường đi chính. Một người tham dự cần đúng một replication slot, và mọi instance được quản lý đều mặc định có wal_level=logical cùng 10 slot, nên rào cản "tăng max_replication_slots" đơn giản là không áp dụng với họ.
• Postgres và ClickPipe của họ nằm trong cùng một tổ chức và đều được tạo bằng clickhousectl; không cần rẽ sang trình wizard trong console.
• Giải thích CDC ở mức tổng quan (đọc write-ahead log) và vì sao các bảng đích mang các cột ghi sổ _peerdb_*; materialized view lọc theo _peerdb_is_deleted = 0.
• Chỉ ra rằng chính log của bộ sinh dữ liệu là dấu hiệu sẵn sàng — ứng dụng chính là phép thăm dò; họ không bao giờ phải poll một status API (các lệnh beta postgres get/list có thể trả về rỗng hoặc FORBIDDEN ngay cả trên một instance khoẻ mạnh).

Lỗi thường gặp

• Mất mật khẩu dùng một lần. Nó chỉ được create hiện đúng một lần. Hãy reset nó: clickhousectl cloud postgres reset-password <service-id>, rồi cập nhật .env.workshop và khởi động lại bộ sinh dữ liệu.
• Bộ sinh dữ liệu ghi log lỗi kết nối lúc đầu. Instance vẫn đang được cấp phát; container thoát ra rồi tự khởi động lại, nên nó tự lành trong khoảng một phút. Chỉ điều tra nếu lỗi kéo dài quá vài phút.
• ClickPipe không kết nối được. Thường là do sai host hoặc mật khẩu, hoặc PGSSLMODE chưa được đặt thành require (managed Postgres bắt buộc TLS).
• Lệch region. Postgres-đến-ClickHouse xuyên region vẫn hoạt động nhưng tăng độ trễ; hãy hướng người tham dự tạo Postgres ở cùng region với ClickHouse service của họ.
• Chưa khởi động bộ sinh dữ liệu, nên trông như không có gì chuyển động — hãy kiểm tra pg-trip-writer đang chạy và log của nó hiện inserted N trips.
• Lệnh tạo pipe thất bại với BAD_REQUEST: table realtime_trips exists and is not empty. Chỉ xảy ra khi chạy lại/khôi phục, không xảy ra với người tham dự mới: việc xoá một ClickPipe sẽ xoá replication slot ở nguồn nhưng để lại bảng đích của nó, và CLI từ chối dùng lại một bảng không rỗng. Hãy dùng quy trình sao lưu có gắn dấu thời gian trong hướng dẫn xử lý sự cố của học viên, rồi tạo lại pipe; đừng mặc định bỏ dữ liệu của người tham dự.
• Managed Postgres không có sẵn trong tổ chức (mức khả dụng ở giai đoạn beta thay đổi) — đây là trường hợp duy nhất cần rơi về pool dùng chung của giảng viên; xem bên dưới.

Phương án dự phòng: Postgres trên cloud do giảng viên quản lý

Nếu tổ chức của người tham dự không tạo được managed Postgres, hãy đưa cho họ một phiếu kết nối tới cloud được quản lý. Pool trên cloud (cùng các lưu ý về slot/sender kèm theo khi quy mô từ 30 người trở lên) được cấp phát và tài liệu hoá trong infra/README.md. Trên đường đi dùng chung, bảng và publication đã được tạo trước, nên log của bộ sinh dữ liệu hiện publication ... already exists thay vì tạo mới — đó là điều dự kiến, không phải lỗi.

Các bước khôi phục

• Xoá và tạo lại ClickPipe bằng các lệnh trong Module 03 của học viên.
• Khởi động lại bộ sinh dữ liệu: docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer (tắt nó bằng --scale pg-trip-writer=0).
• Reset mật khẩu Postgres bị mất bằng clickhousectl cloud postgres reset-password.
• Sau sự kiện, người tham dự xoá ClickPipe của họ (module 09); managed Postgres của một người tham dự là của họ, họ tự xoá từ console hoặc bằng clickhousectl cloud postgres delete <service-id>.