- Primary Key: 가장 간단한 방법은 테이블에 기본 키를 정의하는 것입니다. 이렇게 하면 각 행을 고유하게 식별할 수 있어 업데이트 및 삭제를 추적하는 데 매우 중요합니다. 이 경우 REPLICA IDENTITY를
DEFAULT(기본 동작)로 설정할 수 있습니다. - Replica Identity: 테이블에 기본 키가 없는 경우 replica identity를 설정할 수 있습니다. replica identity는
FULL로 설정할 수 있으며, 이 경우 변경 사항을 식별할 때 전체 행이 사용됩니다. 또는 테이블에 고유 인덱스가 있는 경우 해당 인덱스를 사용하도록 설정한 뒤 REPLICA IDENTITY를USING INDEX index_name으로 설정할 수도 있습니다. replica identity를FULL로 설정하려면 다음 SQL 명령을 사용할 수 있습니다:
REPLICA IDENTITY FULL을 사용하면 성능에 영향을 미칠 수 있으며 WAL도 더 빠르게 증가할 수 있다는 점에 유의하십시오. 특히 기본 키가 없고 업데이트나 삭제가 자주 발생하는 테이블에서는 각 변경 사항마다 더 많은 데이터가 기록되어야 하므로 이러한 영향이 더 크게 나타날 수 있습니다. 테이블의 기본 키 또는 레플리카 아이덴티티 설정과 관련해 확신이 없거나 도움이 필요하면 지원 팀에 문의하여 안내를 받으십시오.
또한 기본 키나 레플리카 아이덴티티가 모두 정의되어 있지 않으면 ClickPipes는 해당 테이블의 변경 사항을 복제할 수 없으며, 복제 과정에서 오류가 발생할 수 있다는 점도 유의해야 합니다. 따라서 ClickPipe를 설정하기 전에 테이블 스키마를 검토하고 이러한 요구 사항을 충족하는지 확인하는 것이 좋습니다.
예, 파티션된 테이블도 기본적으로 지원합니다. 단, PRIMARY KEY 또는 REPLICA IDENTITY가 정의되어 있어야 합니다. PRIMARY KEY와 REPLICA IDENTITY는 부모 테이블과 각 파티션 모두에 정의되어 있어야 합니다. 자세한 내용은 여기에서 확인할 수 있습니다.
네. ClickPipes가 공개 인터넷에 노출되지 않은 데이터 소스에 연결하는 방법은 ClickPipes 네트워킹에서 확인하세요.
ClickPipes for Postgres는 Postgres의 INSERT와 UPDATE를 모두 ClickHouse에서 서로 다른 버전(_peerdb_ 버전 컬럼 사용)을 가진 새 행으로 캡처합니다. ReplacingMergeTree 테이블 엔진은 순서 지정 키(ORDER BY 컬럼)를 기준으로 백그라운드에서 주기적으로 중복 제거를 수행하며, 가장 최신 _peerdb_ 버전의 행만 유지합니다.
Postgres의 DELETE는 삭제된 것으로 표시된 새 행(_peerdb_is_deleted 컬럼 사용)으로 전파됩니다. 중복 제거 프로세스는 비동기적으로 수행되므로 일시적으로 중복이 보일 수 있습니다. 이를 해결하려면 쿼리 계층에서 중복 제거를 처리해야 합니다.
또한 기본적으로 Postgres는 DELETE 작업 중 기본 키 또는 replica identity에 포함되지 않은 컬럼 값은 전송하지 않습니다. DELETE 시 전체 행 데이터를 캡처하려면 REPLICA IDENTITY를 FULL로 설정할 수 있습니다.
자세한 내용은 다음 문서를 참조하십시오:
기본 키는 변경되지 않는 식별자로 사용하는 것이 원칙이므로, PostgreSQL 데이터베이스 설계에서 기본 키 컬럼을 업데이트하는 것은 일반적인 방식이 아닙니다. 대부분의 애플리케이션도 설계상 기본 키 업데이트를 피하므로, 일반적인 사용 사례에서는 이러한 제한이 드물게 문제 됩니다.
기본 키 업데이트 처리를 활성화할 수 있는 실험적 설정이 있기는 하지만, 성능에 상당한 영향을 미치므로 신중한 검토 없이 프로덕션 환경에서 사용하는 것은 권장되지 않습니다.
사용 사례상 PostgreSQL에서 기본 키 컬럼을 업데이트해야 하고 그 변경 사항이 ClickHouse에도 정확히 반영되어야 한다면, 구체적인 요구 사항과 가능한 해결 방안을 논의할 수 있도록 db-integrations-support@clickhouse.com으로 지원 팀에 문의해 주십시오.
자세한 내용은 ClickPipes for Postgres: 스키마 변경 전파 지원 페이지를 참조하십시오.
자세한 가격 정보는 메인 청구 개요 페이지의 ClickPipes for Postgres CDC 가격 섹션을 참조하십시오.
Postgres replication slot 크기가 계속 증가하거나 다시 줄어들지 않는다면, 일반적으로 CDC 파이프라인 또는 복제 프로세스가 WAL(Write-Ahead Log) 레코드를 충분히 빠르게 소비(또는 “재생”)하지 못하고 있다는 의미입니다. 아래에는 가장 일반적인 원인과 대응 방법을 정리했습니다.
-
데이터베이스 활동의 급격한 증가
- 대규모 배치 업데이트, 대량 삽입, 또는 큰 폭의 스키마 변경은 짧은 시간에 많은 WAL 데이터를 생성할 수 있습니다.
- replication slot은 이러한 WAL 레코드가 소비될 때까지 보관하므로, 크기가 일시적으로 급증할 수 있습니다.
-
장시간 실행되는 트랜잭션
- 트랜잭션이 열린 상태로 유지되면 Postgres는 해당 트랜잭션이 시작된 이후 생성된 모든 WAL 세그먼트를 보관해야 하므로, 슬롯 크기가 크게 증가할 수 있습니다.
- 트랜잭션이 무기한 열린 상태로 남지 않도록
statement_timeout및idle_in_transaction_session_timeout을 적절한 값으로 설정하십시오:이 쿼리를 사용해 비정상적으로 오래 실행 중인 트랜잭션을 식별하십시오.
-
유지 관리 또는 유틸리티 작업(예:
pg_repack)pg_repack같은 도구는 전체 테이블을 재작성하여 짧은 시간에 많은 양의 WAL 데이터를 생성할 수 있습니다.- 이러한 작업은 트래픽이 적은 시간대에 예약하거나, 실행 중에는 WAL 사용량을 면밀히 모니터링하십시오.
-
VACUUM 및 VACUUM ANALYZE
- 이러한 작업은 데이터베이스 상태 유지에 필요하지만, 특히 큰 테이블을 스캔할 경우 추가적인 WAL 트래픽을 생성할 수 있습니다.
- autovacuum 튜닝 매개변수를 사용하거나, 수동 VACUUM 작업을 사용량이 적은 시간대에 예약하는 방안을 고려하십시오.
-
복제 소비자가 슬롯을 적극적으로 읽고 있지 않음
- CDC 파이프라인(예: ClickPipes) 또는 다른 복제 소비자가 중지되거나, 일시 중지되거나, 비정상 종료되면 WAL 데이터가 슬롯에 누적됩니다.
- 파이프라인이 지속적으로 실행 중인지 확인하고, 연결 또는 인증 오류가 있는지 로그를 점검하십시오.
json 및 jsonb 컬럼은 네이티브 JSON 타입과 호환되지 않기 때문에 ClickHouse에서는 String 타입으로 복제됩니다. 예를 들면 다음과 같습니다.
- PostgreSQL은 최상위 레벨에서 모든 유효한 JSON 값(문자열, 숫자, 배열)을 허용하지만, ClickHouse의 JSON 타입은 객체만 지원합니다.
- 점이 포함된 키(예: “app.kubernetes.io/name”)는 ClickHouse의 JSON 타입에서 중첩 경로로 해석되므로 데이터 구조가 달라질 수 있습니다.
- sync의 경우 중간에 취소되면 Postgres의 confirmed_flush_lsn이 앞으로 진행되지 않으므로, 다음 sync는 중단된 작업과 동일한 위치에서 시작하여 데이터 일관성을 보장합니다.
- normalize의 경우 ReplacingMergeTree의 삽입 순서가 중복 제거를 처리합니다.
snapshot number of tables in parallel 값을 늘리거나, 큰 테이블에 대해 인덱스가 있는 사용자 지정 파티셔닝 컬럼을 지정할 수 있습니다.
ClickPipes가 publication을 관리하도록 할 수도 있고(추가 권한 필요), 직접 생성할 수도 있습니다. ClickPipes 관리형 publication을 사용하면 파이프를 편집할 때 테이블 추가 및 제거가 자동으로 처리됩니다. 직접 관리하는 경우에는 복제할 테이블만 포함하도록 publication 범위를 신중하게 설정하십시오. 불필요한 테이블을 포함하면 Postgres WAL 디코딩이 느려집니다.
publication에 테이블을 하나라도 포함하는 경우, 해당 테이블에 기본 키가 있거나 REPLICA IDENTITY FULL이 설정되어 있는지 확인하십시오. 기본 키가 없는 테이블이 있을 때 모든 테이블을 대상으로 publication을 생성하면 해당 테이블에서 DELETE 및 UPDATE 작업이 실패합니다.
데이터베이스에서 기본 키가 없는 테이블을 식별하려면 다음 쿼리를 사용할 수 있습니다.
-
기본 키가 없는 테이블을 ClickPipes에서 제외:
기본 키가 있는 테이블만 포함되도록 publication을 생성합니다:
-
기본 키가 없는 테이블을 ClickPipes에 포함:
기본 키가 없는 테이블을 포함하려면 해당 테이블의 replica identity를
FULL로 변경해야 합니다. 이렇게 하면 UPDATE 및 DELETE 작업이 올바르게 수행됩니다:
- 최소 기준:
max_slot_wal_keep_size를 최소 2일치 WAL 데이터를 보관하도록 설정하십시오. - 대규모 데이터베이스(트랜잭션 볼륨이 높은 환경): 하루 최대 WAL 생성량의 2~3배 이상을 보관하십시오.
- 스토리지 제약이 있는 환경: 복제 안정성을 유지하면서 디스크가 부족해지지 않도록 이 값을 보수적으로 조정하십시오.
PostgreSQL 10 이상
PostgreSQL 9.6 이하 버전:
- 위 쿼리를 하루 중 여러 시간대에 실행하고, 특히 트랜잭션이 매우 많은 시간대에 실행하십시오.
- 24시간 동안 생성되는 WAL 양을 계산하십시오.
- 충분한 보존 기간을 확보할 수 있도록 해당 값에 2 또는 3을 곱하십시오.
max_slot_wal_keep_size를 MB 또는 GB 단위의 계산된 값으로 설정하십시오.
예시
ReceiveMessage는 Postgres 논리 디코딩(logical decoding) protocol에서 복제 스트림의 메시지를 읽는 함수입니다. EOF(End of File) 오류는 복제 스트림을 읽는 도중 Postgres 서버와의 연결이 예기치 않게 종료되었음을 의미합니다.
이 오류는 복구 가능한 오류이며, 전혀 치명적이지 않습니다. ClickPipes는 자동으로 다시 연결을 시도하고 복제 프로세스를 재개합니다.
다음과 같은 몇 가지 이유로 발생할 수 있습니다.
- 네트워크 문제: 일시적인 네트워크 중단으로 인해 연결이 끊어질 수 있습니다.
- Postgres 서버 재시작: Postgres 서버가 재시작되거나 비정상 종료되면 연결이 끊어집니다.
max_slot_wal_keep_size 설정값이 너무 낮기 때문입니다(예: 수 GB). 이 값을 늘리는 것을 권장합니다. max_slot_wal_keep_size 조정 방법은 이 섹션을 참조하세요. 이상적으로는 replication slot 무효화를 방지하기 위해 최소 200GB로 설정해야 합니다.
드문 경우지만 max_slot_wal_keep_size가 구성되지 않았는데도 이 문제가 발생하는 사례가 있었습니다. 이는 PostgreSQL의 복잡하고 드문 버그 때문일 수 있지만, 정확한 원인은 아직 명확하지 않습니다.
ClickHouse에서 OOM이 발생하는 흔한 원인 중 하나는 서비스 크기가 충분하지 않기 때문입니다. 즉, 현재 서비스 구성이 수집 부하를 효과적으로 처리할 만큼 충분한 리소스(예: 메모리 또는 CPU)를 갖추고 있지 않다는 뜻입니다. ClickPipe 데이터 수집 요구 사항을 충족할 수 있도록 서비스를 스케일업할 것을 강력히 권장합니다.
또 다른 원인으로는, 최적화가 충분하지 않은 조인이 포함된 다운스트림 materialized view가 있는 경우가 있습니다.
-
LEFT JOIN의 오른쪽 테이블이 매우 큰 경우에 사용할 수 있는 일반적인JOIN최적화 기법이 있습니다. 이 경우 쿼리를RIGHT JOIN으로 재작성하고 더 큰 테이블을 왼쪽으로 옮기십시오. 그러면 쿼리 플래너가 메모리를 더 효율적으로 사용할 수 있습니다. -
JOIN의 또 다른 최적화 방법은subqueries또는CTEs를 사용해 테이블을 명시적으로 필터링한 다음, 이 서브쿼리들 사이에서JOIN을 수행하는 것입니다. 이렇게 하면 플래너가 행을 효율적으로 필터링하고JOIN을 수행하는 데 도움이 되는 힌트를 얻을 수 있습니다.
invalid snapshot identifier 오류는 ClickPipes와 Postgres 데이터베이스 간 연결이 끊어질 때 발생합니다. 이는 게이트웨이 timeout, 데이터베이스 재시작, 또는 기타 일시적인 문제로 인해 발생할 수 있습니다.
초기 적재가 진행 중일 때는 Postgres 데이터베이스에서 업그레이드나 재시작처럼 서비스에 영향을 줄 수 있는 작업을 수행하지 말고, 데이터베이스에 대한 네트워크 연결이 안정적으로 유지되도록 하는 것이 좋습니다.
이 문제를 해결하려면 ClickPipes UI에서 resync를 트리거할 수 있습니다. 그러면 초기 적재 프로세스가 처음부터 다시 시작됩니다.
Postgres에서 publication을 삭제하면 ClickPipe가 소스의 변경 사항을 가져오려면 publication이 필요하므로 ClickPipe 연결이 끊어집니다. 이 경우 일반적으로 publication이 더 이상 존재하지 않는다는 오류 알림을 받게 됩니다.
publication을 삭제한 후 ClickPipe를 복구하려면 다음 단계를 수행하십시오.
- Postgres에서 동일한 이름과 필요한 테이블로 새 publication을 생성합니다
- ClickPipe의 설정 탭에서 ‘Resync tables’ 버튼을 클릭합니다
소스 Postgres 데이터베이스에서 데이터가 삭제되더라도 ClickHouse에 전체 이력 기록을 유지해야 합니다. ClickPipes에서 Postgres의 DELETE 및 TRUNCATE 작업을 완전히 무시할 수 있습니까?
- 사용자에게 원본 테이블을 읽을 수 있는 충분한 권한이 있는지 확인합니다.
- ClickHouse 측에 행을 필터링하는 행 정책이 있는지 확인합니다.
Advanced Settings 섹션에서 아래 스위치를 켜면 ClickPipes가 failover가 활성화된 replication slot을 생성할 수 있습니다. 이 기능을 사용하려면 Postgres 버전이 17 이상이어야 합니다.

ReorderBufferPreserveLastSpilledSnapshot 루틴에서 발생한다는 점을 보면, logical decoding이 디스크에 spill된 snapshot을 읽지 못하는 것으로 보입니다. logical_decoding_work_mem 값을 더 크게 늘려 보십시오.
Postgres는 고정된 프로토콜을 따르는 메시지 형식으로 변경 정보를 전송합니다. 이러한 오류는 ClickPipe가 파싱할 수 없는 메시지를 수신할 때 발생하며, 전송 중 데이터가 손상되었거나 잘못된 메시지가 전송된 경우가 원인일 수 있습니다. 정확한 원인은 사례마다 다르지만, Neon Postgres 소스에서 이런 사례가 여러 건 확인되었습니다. Neon에서도 이 문제가 발생한다면 해당 업체에 지원 티켓을 제출하십시오. 그 밖의 경우에는 안내를 위해 당사 지원팀에 문의하십시오.
아직은 지원되지 않습니다. 대신 포함하려는 컬럼이 있는 테이블을 resync할 수 있습니다.
이 문제는 몇 가지 이유로 발생할 수 있으며, 주로 스냅샷에 필요한 사전 요구 사항을 충족하는 데 평소보다 더 오래 걸리기 때문입니다. 자세한 내용은 병렬 스냅샷 관련 문서 여기를 참조하십시오.
병렬 스냅샷은 테이블의 논리적 파티션을 가져오기 위해 몇 가지 초기 단계를 수행합니다. 테이블이 작으면 몇 초 안에 완료되지만, 매우 큰(테라바이트급) 테이블은 더 오래 걸릴 수 있습니다. 스냅샷을 위한 파티션을 가져오는 과정과 관련해 오래 실행 중인 쿼리가 있는지 확인하려면 Source 탭에서 Postgres source에서 실행 중인 쿼리를 모니터링할 수 있습니다. 파티션을 가져오면 데이터 유입이 시작됩니다.
Activity 섹션의 Source 탭에서 CREATE_REPLICATION_SLOT 쿼리가 Lock 상태에 머물러 있는 것을 확인할 수 있습니다. 이는 Postgres가 replication slot을 생성할 때 사용하는 객체에 대해 다른 트랜잭션이 잠금을 보유하고 있기 때문일 수 있습니다.
차단 중인 쿼리를 확인하려면 Postgres 소스에서 아래 쿼리를 실행하십시오: