메인 콘텐츠로 건너뛰기
이 엔진은 Atomic 엔진을 기반으로 합니다. 특정 데이터베이스에 대해 ZooKeeper에 기록되고 해당 데이터베이스의 모든 레플리카에서 실행되는 DDL 로그를 통해 메타데이터 복제를 지원합니다. 하나의 ClickHouse 서버에서는 여러 개의 복제된 데이터베이스를 동시에 실행하고 업데이트할 수 있습니다. 하지만 동일한 복제된 데이터베이스에 여러 개의 레플리카를 둘 수는 없습니다.

​
데이터베이스 만들기

CREATE DATABASE testdb [UUID '...'] ENGINE = Replicated('zoo_path', 'shard_name', 'replica_name') [SETTINGS ...]
엔진 매개변수
  • zoo_path — ZooKeeper 경로입니다. 동일한 ZooKeeper 경로는 동일한 데이터베이스를 가리킵니다.
  • shard_name — 세그먼트 이름입니다. 데이터베이스 레플리카는 shard_name을 기준으로 세그먼트로 그룹화됩니다.
  • replica_name — 레플리카 이름입니다. 동일한 세그먼트에 속한 모든 레플리카의 이름은 서로 달라야 합니다.
매개변수는 생략할 수 있으며, 이 경우 누락된 매개변수에는 기본값이 사용됩니다. zoo_path에 매크로 {uuid}가 포함된 경우, 이 데이터베이스의 모든 레플리카가 동일한 UUID를 사용하도록 명시적으로 UUID를 지정하거나 CREATE 문에 ON CLUSTER를 추가해야 합니다. ReplicatedMergeTree 테이블에서 인수를 지정하지 않으면 기본 인수인 /clickhouse/tables/{uuid}/{shard} 및 {replica}가 사용됩니다. 이 값은 서버 설정 default_replica_path 및 default_replica_name에서 변경할 수 있습니다. 매크로 {uuid}는 테이블의 UUID로 치환되며, {shard}와 {replica}는 데이터베이스 엔진 인수가 아니라 서버 구성의 값으로 치환됩니다. 다만 앞으로는 복제된 데이터베이스의 shard_name과 replica_name도 사용할 수 있게 될 예정입니다. 기본 ZooKeeper 클러스터 대신 복제된 데이터베이스의 메타데이터 저장에 보조 ZooKeeper 클러스터를 사용하는 것도 지원됩니다. 다음과 같이 보조 ZooKeeper 클러스터를 사용하여 SQL로 복제된 데이터베이스를 생성할 수 있습니다: 
CREATE DATABASE database_name ENGINE = Replicated('zookeeper_name_configured_in_auxiliary_zookeepers:path', 'shard_name', 'replica_name')

​
세부 사항 및 권장 사항

Replicated 데이터베이스를 사용하는 DDL 쿼리는 ON CLUSTER 쿼리와 유사하게 동작하지만, 몇 가지 차이점이 있습니다. 먼저 DDL 요청은 initiator(원래 사용자 요청을 받은 호스트)에서 실행을 시도합니다. 요청이 수행되지 않으면 사용자는 즉시 오류를 받으며, 다른 호스트는 이를 수행하려고 시도하지 않습니다. 요청이 initiator에서 성공적으로 완료되면, 다른 모든 호스트는 완료될 때까지 자동으로 재시도합니다. initiator는 다른 호스트에서 쿼리가 완료될 때까지 기다리며(distributed_ddl_task_timeout을 초과하지 않음), 각 호스트의 쿼리 실행 상태가 담긴 테이블을 반환합니다. 오류 발생 시 동작은 distributed_ddl_output_mode 설정으로 제어되며, Replicated 데이터베이스에서는 이를 null_status_on_timeout으로 설정하는 것이 좋습니다. 즉, 일부 호스트가 distributed_ddl_task_timeout 내에 요청을 실행하지 못한 경우 예외를 발생시키지 말고, 해당 호스트의 상태를 테이블에 NULL로 표시합니다. system.clusters 시스템 테이블에는 복제된 데이터베이스와 같은 이름의 클러스터가 있으며, 이 클러스터는 해당 데이터베이스의 모든 레플리카로 구성됩니다. 이 클러스터는 레플리카를 생성하거나 삭제할 때 자동으로 업데이트되며, 분산 테이블에 사용할 수 있습니다. 데이터베이스의 새 레플리카를 생성하면 이 레플리카는 스스로 테이블을 생성합니다. 레플리카를 오랫동안 사용할 수 없어 복제 로그보다 뒤처진 경우, 로컬 메타데이터를 ZooKeeper의 현재 메타데이터와 비교하고, 데이터가 있는 추가 테이블은 별도의 비복제 데이터베이스로 이동한 뒤(불필요한 항목이 실수로 삭제되는 일을 방지하기 위해), 누락된 테이블을 생성하고, 이름이 변경된 테이블이 있으면 테이블 이름을 업데이트합니다. 데이터는 ReplicatedMergeTree 수준에서 복제되므로, 테이블이 복제되지 않으면 데이터도 복제되지 않습니다(데이터베이스는 메타데이터만 담당합니다). ALTER TABLE FREEZE|ATTACH|FETCH|DROP|DROP DETACHED|DETACH PARTITION|PART 쿼리는 허용되지만 복제되지는 않습니다. 데이터베이스 엔진은 현재 레플리카에 대해서만 파티션/파트를 추가, fetch 또는 제거합니다. 그러나 테이블 자체가 Replicated 테이블 엔진을 사용한다면 ATTACH 사용 후 데이터가 복제됩니다. 테이블 복제를 유지하지 않고 클러스터만 구성해야 한다면, 클러스터 디스커버리 기능을 참조하십시오.

​
사용 예시

호스트 3개로 클러스터를 생성합니다: 
node1 :) CREATE DATABASE r ENGINE=Replicated('some/path/r','shard1','replica1');
node2 :) CREATE DATABASE r ENGINE=Replicated('some/path/r','shard1','other_replica');
node3 :) CREATE DATABASE r ENGINE=Replicated('some/path/r','other_shard','{replica}');
암시적 매개변수를 사용한 클러스터 데이터베이스 생성: 
CREATE DATABASE r ON CLUSTER default ENGINE=Replicated;
DDL 쿼리 실행: 
CREATE TABLE r.rmt (n UInt64) ENGINE=ReplicatedMergeTree ORDER BY n;

┌─────hosts────────────┬──status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ shard1|replica1      │    0    │       │          2          │        0         │
│ shard1|other_replica │    0    │       │          1          │        0         │
│ other_shard|r1       │    0    │       │          0          │        0         │
└──────────────────────┴─────────┴───────┴─────────────────────┴──────────────────┘
시스템 테이블을 표시합니다: 
SELECT cluster, shard_num, replica_num, host_name, host_address, port, is_local
FROM system.clusters WHERE cluster='r';

┌─cluster─┬─shard_num─┬─replica_num─┬─host_name─┬─host_address─┬─port─┬─is_local─┐
│ r       │     1     │      1      │   node3   │  127.0.0.1   │ 9002 │     0    │
│ r       │     2     │      1      │   node2   │  127.0.0.1   │ 9001 │     0    │
│ r       │     2     │      2      │   node1   │  127.0.0.1   │ 9000 │     1    │
└─────────┴───────────┴─────────────┴───────────┴──────────────┴──────┴──────────┘
분산 테이블 생성 및 데이터 삽입: 
node2 :) CREATE TABLE r.d (n UInt64) ENGINE=Distributed('r','r','rmt', n % 2);
node3 :) INSERT INTO r.d SELECT * FROM numbers(10);
node1 :) SELECT materialize(hostName()) AS host, groupArray(n) FROM r.d GROUP BY host;

┌─hosts─┬─groupArray(n)─┐
│ node3 │  [1,3,5,7,9]  │
│ node2 │  [0,2,4,6,8]  │
└───────┴───────────────┘
호스트를 하나 더 추가하여 레플리카를 구성하는 방법: 
node4 :) CREATE DATABASE r ENGINE=Replicated('some/path/r','other_shard','r2');
zoo_path에 매크로 {uuid}를 사용하는 경우 다른 호스트에 레플리카 추가: 
node1 :) SELECT uuid FROM system.databases WHERE database='r';
node4 :) CREATE DATABASE r UUID '<uuid from previous query>' ENGINE=Replicated('some/path/{uuid}','other_shard','r2');
클러스터 구성은 다음과 같습니다: 
┌─cluster─┬─shard_num─┬─replica_num─┬─host_name─┬─host_address─┬─port─┬─is_local─┐
│ r       │     1     │      1      │   node3   │  127.0.0.1   │ 9002 │     0    │
│ r       │     1     │      2      │   node4   │  127.0.0.1   │ 9003 │     0    │
│ r       │     2     │      1      │   node2   │  127.0.0.1   │ 9001 │     0    │
│ r       │     2     │      2      │   node1   │  127.0.0.1   │ 9000 │     1    │
└─────────┴───────────┴─────────────┴───────────┴──────────────┴──────┴──────────┘
분산 테이블도 새 호스트의 데이터를 가져오게 됩니다: 
node2 :) SELECT materialize(hostName()) AS host, groupArray(n) FROM r.d GROUP BY host;

┌─hosts─┬─groupArray(n)─┐
│ node2 │  [1,3,5,7,9]  │
│ node4 │  [0,2,4,6,8]  │
└───────┴───────────────┘

​
설정

다음 설정을 지원합니다:
SettingDefaultDescription
max_broken_tables_ratio1오래된 테이블 수의 비율이 전체 테이블 대비 이 값보다 크면 레플리카를 자동으로 복구하지 않습니다
max_replication_lag_to_enqueue50레플리카의 복제 지연이 이 값보다 크면 쿼리 실행을 시도할 때 예외를 발생시킵니다
wait_entry_commited_timeout_sec3600제한 시간을 초과했지만 initiator 호스트가 아직 이를 실행하지 않은 경우, 레플리카는 쿼리 취소를 시도합니다
collection_name클러스터 인증에 필요한 모든 정보가 정의된 server의 config에 있는 collection 이름입니다
check_consistencytrue로컬 메타데이터와 Keeper의 메타데이터 일관성을 확인하고, 불일치가 있으면 레플리카 복구를 수행합니다
max_retries_before_automatic_recovery10큐 항목 실행의 최대 시도 횟수입니다. 이를 초과하면 레플리카를 손실된 것으로 표시하고 snapshot에서 복구합니다(0은 무한을 의미합니다)
allow_skipping_old_temporary_tables_ddls_of_refreshable_materialized_viewsfalse활성화하면 Replicated 데이터베이스에서 DDLs를 처리할 때, 가능하면 갱신 가능 구체화 뷰의 임시 테이블에 대한 DDL 생성 및 교환을 건너뜁니다
logs_to_keep1000Replicated 데이터베이스에 대해 ZooKeeper에 유지할 기본 로그 수입니다.
default_replica_path/clickhouse/databases/{uuid}ZooKeeper에 있는 데이터베이스 경로입니다. 인수가 생략된 경우 데이터베이스 생성 시 사용됩니다.
default_replica_shard_name{shard}데이터베이스 내 레플리카의 세그먼트 이름입니다. 인수가 생략된 경우 데이터베이스 생성 시 사용됩니다.
default_replica_name{replica}데이터베이스 내 레플리카 이름입니다. 인수가 생략된 경우 데이터베이스 생성 시 사용됩니다.
internal_replicationfalse이 Replicated 데이터베이스의 클러스터로 생성된 분산 테이블이 데이터를 레플리카 중 하나로 보낼지(내부 복제는 클러스터의 레플리카가 자체적으로 복제를 수행함을 의미함), 또는 모든 레플리카로 보낼지(내부 복제를 사용하지 않으면 분산 테이블이 삽입된 데이터를 모든 레플리카로 전송함)를 지정합니다
기본값은 설정 파일에서 재정의할 수 있습니다 
<clickhouse>
    <database_replicated>
        <max_broken_tables_ratio>0.75</max_broken_tables_ratio>
        <max_replication_lag_to_enqueue>100</max_replication_lag_to_enqueue>
        <wait_entry_commited_timeout_sec>1800</wait_entry_commited_timeout_sec>
        <collection_name>postgres1</collection_name>
        <check_consistency>false</check_consistency>
        <max_retries_before_automatic_recovery>5</max_retries_before_automatic_recovery>
        <default_replica_path>/clickhouse/databases/{uuid}</default_replica_path>
        <default_replica_shard_name>{shard}</default_replica_shard_name>
        <default_replica_name>{replica}</default_replica_name>
        <internal_replication>false</internal_replication>
    </database_replicated>
</clickhouse>
마지막 수정일 2026년 6월 10일