03 매니지드 Postgres CDC

학습자 레슨 03 매니지드 Postgres CDC에 대응하는 진행자용 안내서입니다.

타이밍

약 20분. 매니지드 Postgres 인스턴스는 clickhousectl cloud postgres create 이후 약 1분 안에 연결을 받기 시작하므로, 여러분이 CDC를 설명하는 동안 참가자들이 인스턴스를 프로비저닝하고 환경 변수를 채울 수 있습니다. ClickPipe는 스냅샷을 만들고 스트리밍을 시작하기까지 보통 몇 분이 걸리지만, 검증 과정에서 프로비저닝이 10분을 넘는 경우도 관측되었습니다. 일찍 시작하고, 완료 시각을 약속하는 대신 학습자용 문제 해결 에스컬레이션 점검 항목을 활용하세요.

토크 트랙

• 각 참가자는 자신의 트라이얼 조직에서 ClickHouse가 관리하는 자기 소유의 Postgres를 생성합니다 — 기본 경로에는 공용 인스턴스가 없습니다. 참가자 한 명에게는 복제 슬롯이 정확히 하나 필요하고, 모든 매니지드 인스턴스는 기본적으로 wal_level=logical과 슬롯 10개로 제공되므로 "max_replication_slots를 올려라"라는 관문은 이들에게는 해당하지 않습니다.
• 참가자의 Postgres와 ClickPipe는 같은 조직에 있으며 둘 다 clickhousectl로 생성됩니다. 콘솔 위저드로 갈라지는 경로는 필요하지 않습니다.
• CDC를 큰 그림에서 설명하고(write-ahead log를 읽습니다), 대상 테이블에 왜 _peerdb_* 관리용 컬럼이 붙는지 설명하세요. materialized view는 _peerdb_is_deleted = 0으로 필터링합니다.
• 준비 완료 신호는 제너레이터 자신의 로그라는 점을 짚어주세요 — 앱이 곧 프로브입니다. 참가자는 상태 API를 폴링하지 않습니다(베타인 postgres get/list 호출은 인스턴스가 정상이어도 빈 값이나 FORBIDDEN을 반환할 수 있습니다).

흔한 실패 사례

• 일회성 비밀번호를 분실. create가 단 한 번만 보여줍니다. 재설정하세요: clickhousectl cloud postgres reset-password <service-id>, 그다음 .env.workshop을 갱신하고 제너레이터를 재시작합니다.
• 제너레이터가 처음에 연결 오류를 로그에 남김. 인스턴스가 아직 프로비저닝 중입니다. 컨테이너가 종료되고 자동으로 재시작되므로 약 1분 안에 스스로 복구됩니다. 오류가 2~3분 넘게 계속될 때만 조사하세요.
• ClickPipe가 연결할 수 없음. 보통 호스트나 비밀번호가 잘못되었거나, PGSSLMODE가 require로 설정되지 않은 경우입니다(매니지드 Postgres는 TLS를 필수로 요구합니다).
• 리전 불일치. 리전을 넘는 Postgres-ClickHouse 연결도 동작하지만 지연이 늘어납니다. 참가자가 자신의 ClickHouse 서비스와 같은 리전에 Postgres를 만들도록 유도하세요.
• 데이터 제너레이터가 시작되지 않아 아무것도 움직이지 않는 것처럼 보임 — pg-trip-writer가 올라와 있고 로그에 inserted N trips가 보이는지 확인하세요.
• 파이프 생성이 BAD_REQUEST: table realtime_trips exists and is not empty로 실패. 새 참가자가 아니라 재실행/초기화 때만 발생합니다. ClickPipe를 삭제하면 소스의 복제 슬롯은 사라지지만 대상 테이블은 남고, CLI는 비어 있지 않은 테이블을 재사용하기를 거부합니다. 학습자 문제 해결 가이드의 타임스탬프 백업 절차를 사용한 뒤 파이프를 다시 만드세요. 기본적으로 참가자 데이터를 버리지 마세요.
• 조직에서 매니지드 Postgres를 사용할 수 없음(베타 제공 범위는 다릅니다) — 이것이 공용 강사 풀로 대체하는 유일한 경우입니다. 아래를 참고하세요.

대체 경로: 강사가 관리하는 클라우드 Postgres

참가자의 조직에서 매니지드 Postgres를 만들 수 없으면 매니지드 클라우드 연결 정보를 전달하세요. 클라우드 풀(그리고 30명 이상 규모에서 따라오는 슬롯/sender 관련 주의 사항)은 infra/README.md에 프로비저닝 방법과 함께 문서화되어 있습니다. 공용 경로에서는 테이블과 publication이 미리 생성되어 있으므로 제너레이터 로그에 새로 만들었다는 내용 대신 publication ... already exists가 표시됩니다 — 오류가 아니라 예상된 결과입니다.

초기화 절차

• 학습자 모듈 03의 명령으로 ClickPipe를 삭제하고 다시 만드세요.
• 데이터 제너레이터를 재시작하세요: docker compose --profile cdc --env-file .env.workshop -f docker-compose.workshop.yml up -d pg-trip-writer (--scale pg-trip-writer=0으로 끕니다).
• 분실한 Postgres 비밀번호는 clickhousectl cloud postgres reset-password로 재설정하세요.
• 행사가 끝나면 참가자는 자신의 ClickPipe를 삭제합니다(모듈 09). 참가자의 매니지드 Postgres는 본인 소유이므로 콘솔에서 또는 clickhousectl cloud postgres delete <service-id>로 삭제하면 됩니다.