ON CLUSTER — 스키마 변경을 클러스터 전체 노드에 한 번에 전파하기
ClickHouse ON CLUSTER 분산 DDL 및 TTL GROUP BY 공식 문서 종합 (웹 리서치, 2026) — ClickHouse 공식 문서(sql-reference/distributed-ddl, guides/developer/ttl) ClickHouse 공식 문서 Distributed DDL Queries
이 모듈을 다 읽으면
- ON CLUSTER가 DDL을 여러 노드에 전파하는 조율 방식을 설명할 수 있다
- 일부 레플리카가 오프라인일 때 DDL이 어떻게 처리되는지 설명할 수 있다
clickhouse-learn-11에서 다룬 ReplicatedMergeTree+ClickHouse Keeper 기반 조율을 전제로, 이 조율 인프라를 이용해 CREATE/DROP/ALTER 같은 스키마 변경을 클러스터의 모든 노드에 한 번의 쿼리로 전파하는 ON CLUSTER 절을 정리한다.
한 노드가 아니라 클러스터 전체에 전파
일반적인 CREATE/DROP/ALTER/RENAME 쿼리는 접속한 노드 하나에만 적용된다. 여기에 ON CLUSTER 클러스터이름 절을 붙이면, 같은 스키마 변경이 그 클러스터에 속한 모든 노드에 전파돼 각자 실행된다 — 여러 노드에 같은 DDL을 일일이 반복해서 실행할 필요 없이, 관리자가 한 번의 쿼리로 인프라 전체에 일관된 스키마 변경을 적용할 수 있다.
핵심 포인트
- ON CLUSTER 클러스터이름을 붙이면 CREATE/DROP/ALTER/RENAME이 그 클러스터의 모든 노드에 전파돼 각자 실행됨
- 여러 노드에 같은 DDL을 일일이 반복 실행할 필요 없이 한 번의 쿼리로 인프라 전체에 일관된 변경 적용
조율 — ClickHouse Keeper/ZooKeeper의 분산 DDL 큐
이 전파가 동작하려면 모든 호스트가 동일한 클러스터 정의를 갖고 있어야 하고, 각자 ClickHouse Keeper(또는 ZooKeeper) 서버에 연결돼 있어야 한다 — clickhouse-learn-11에서 다룬 조율 서비스가 여기서도 핵심 역할을 하는데, 이번에는 데이터 복제가 아니라 DDL 작업 큐를 조율하는 데 쓰인다. 각 호스트는 이 큐에서 자신에게 해당하는 DDL 작업을 가져와 로컬로 실행한다.
핵심 포인트
- 모든 호스트가 동일한 클러스터 정의를 갖고 Keeper/ZooKeeper에 연결돼 있어야 ON CLUSTER 전파가 동작
- clickhouse-learn-11의 조율 서비스가 이번엔 데이터 복제가 아니라 DDL 작업 큐 조율에 쓰임 — 각 호스트가 큐에서 자기 몫을 가져와 로컬 실행
일부 호스트가 오프라인이면 — 비동기 실행과 상태 확인
DDL 실행은 비동기적이다 — 클러스터의 일부 호스트가 그 순간 오프라인이어도, 그 호스트의 로컬 버전 쿼리는 나중에 다시 온라인이 됐을 때 결국 실행된다(블로킹 없이 대기). 다만 하나의 호스트 안에서는 쿼리들이 실행되는 순서가 보장된다. 관리자는 system.distributed_ddl_queue 테이블을 조회해 클러스터 전체에서 이 DDL 작업이 어디까지 실행됐는지, 어느 호스트가 아직 처리 못했는지 상태를 확인할 수 있다.
핵심 포인트
- DDL 실행은 비동기 — 오프라인 호스트는 나중에 온라인이 되면 결국 실행(블로킹 없음), 단일 호스트 내에서는 실행 순서 보장
- system.distributed_ddl_queue로 클러스터 전체의 DDL 실행 상태(어느 호스트가 아직 처리 안 했는지)를 확인 가능