El motor se basa en el motor Atomic. Admite la replicación de los metadatos mediante un log de DDL que se escribe en ZooKeeper y se ejecuta en todas las réplicas de una base de datos determinada.
Un servidor de ClickHouse puede tener varias bases de datos Replicated en funcionamiento y actualizándose al mismo tiempo. Pero no puede haber varias réplicas de la misma base de datos Replicated.
CREATE DATABASE testdb [UUID '...'] ENGINE = Replicated('zoo_path', 'shard_name', 'replica_name') [SETTINGS ...]
zoo_path — Ruta de ZooKeeper. La misma ruta de ZooKeeper corresponde a la misma base de datos.shard_name — Nombre del segmento. Las réplicas de la base de datos se agrupan en segmentos según shard_name.replica_name — Nombre de la réplica. Los nombres de las réplicas deben ser distintos para todas las réplicas del mismo segmento.
Los parámetros pueden omitirse; en ese caso, los que falten se sustituyen por valores predeterminados.
Si zoo_path contiene la macro {uuid}, es obligatorio especificar un UUID explícito o añadir ON CLUSTER a la sentencia CREATE para garantizar que todas las réplicas usen el mismo UUID para esta base de datos.
En las tablas ReplicatedMergeTree, si no se proporcionan argumentos, se usan los argumentos predeterminados: /clickhouse/tables/{uuid}/{shard} y {replica}. Estos se pueden cambiar en la configuración del servidor default_replica_path y default_replica_name. La macro {uuid} se expande al UUID de la tabla; {shard} y {replica} se expanden a los valores de la configuración del servidor, no a los argumentos del motor de base de datos. Sin embargo, en el futuro será posible usar shard_name y replica_name de la base de datos Replicated.
También se admite un clúster auxiliar de ZooKeeper para almacenar los metadatos de una base de datos replicada en lugar de usar el clúster de ZooKeeper predeterminado. Podemos usar SQL para crear la base de datos replicada con un clúster auxiliar de ZooKeeper de la siguiente manera:
CREATE DATABASE database_name ENGINE = Replicated('zookeeper_name_configured_in_auxiliary_zookeepers:path', 'shard_name', 'replica_name')
Particularidades y recomendaciones
Replicated funcionan de forma similar a las consultas ON CLUSTER, aunque con pequeñas diferencias.
En primer lugar, la solicitud DDL intenta ejecutarse en el iniciador (el host que recibió originalmente la solicitud del usuario). Si la solicitud no se completa, el usuario recibe inmediatamente un error y los demás hosts no intentan completarla. Si la solicitud se completa correctamente en el iniciador, todos los demás hosts la reintentarán automáticamente hasta completarla. El iniciador intentará esperar a que la consulta se complete en los demás hosts (durante no más de distributed_ddl_task_timeout) y devolverá una tabla con los estados de ejecución de la consulta en cada host.
El comportamiento en caso de errores está regulado por la configuración distributed_ddl_output_mode; para una base de datos Replicated es mejor establecerla en null_status_on_timeout, es decir, si algunos hosts no tienen tiempo de ejecutar la solicitud dentro de distributed_ddl_task_timeout, no se debe lanzar una excepción, sino mostrar el estado NULL para ellos en la tabla.
La tabla del sistema system.clusters contiene un clúster con el mismo nombre que la base de datos replicada, compuesto por todas las réplicas de la base de datos. Este clúster se actualiza automáticamente al crear o eliminar réplicas, y puede usarse para tablas Distributed.
Al crear una nueva réplica de la base de datos, esta réplica crea las tablas por sí sola. Si la réplica ha estado no disponible durante mucho tiempo y se ha quedado rezagada con respecto al log de replicación, comprueba sus metadatos locales con los metadatos actuales en ZooKeeper, mueve las tablas adicionales con datos a una base de datos no replicada independiente (para no eliminar accidentalmente nada de más), crea las tablas que faltan y actualiza los nombres de las tablas si se han renombrado. Los datos se replican a nivel de ReplicatedMergeTree, es decir, si la tabla no está replicada, los datos no se replicarán (la base de datos solo es responsable de los metadatos).
Las consultas ALTER TABLE FREEZE|ATTACH|FETCH|DROP|DROP DETACHED|DETACH PARTITION|PART están permitidas, pero no se replican. El motor de base de datos solo añadirá/recuperará/eliminará la partición/parte en la réplica actual. Sin embargo, si la propia tabla usa un motor de tabla Replicated, los datos se replicarán después de usar ATTACH.
Si solo necesita configurar un clúster sin mantener la replicación de tablas, consulte la funcionalidad Cluster Discovery.
Crear un clúster con tres hosts:
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;
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');
{uuid} en zoo_path:
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] │
└───────┴───────────────┘
| Setting | Default | Description |
|---|
max_broken_tables_ratio | 1 | No recuperar automáticamente la réplica si la proporción de tablas obsoletas respecto del total de tablas es mayor |
max_replication_lag_to_enqueue | 50 | La réplica generará una excepción al intentar ejecutar una consulta si su retraso de replicación es mayor |
wait_entry_commited_timeout_sec | 3600 | Las réplicas intentarán cancelar la consulta si se supera el tiempo de espera, pero el host iniciador aún no la ha ejecutado |
collection_name | | Nombre de una colección definida en la configuración del servidor, donde se define toda la información para la autenticación del cluster |
check_consistency | true | Comprobar la consistencia de los metadatos locales y los metadatos en Keeper, y recuperar la réplica en caso de inconsistencia |
max_retries_before_automatic_recovery | 10 | Número máximo de intentos para ejecutar una entrada de la cola antes de marcar la réplica como perdida y recuperarla desde una instantánea (0 significa infinito) |
allow_skipping_old_temporary_tables_ddls_of_refreshable_materialized_views | false | Si está habilitado, al procesar DDLs en bases de datos Replicated, se omite la creación y el intercambio de DDLs de las tablas temporales de las vistas materializadas actualizables cuando sea posible |
logs_to_keep | 1000 | Número predeterminado de logs que se conservarán en ZooKeeper para la base de datos Replicated. |
default_replica_path | /clickhouse/databases/{uuid} | La ruta de la base de datos en ZooKeeper. Se usa durante la creación de la base de datos si se omiten los argumentos. |
default_replica_shard_name | {shard} | El nombre del segmento de la réplica en la base de datos. Se usa durante la creación de la base de datos si se omiten los argumentos. |
default_replica_name | {replica} | El nombre de la réplica en la base de datos. Se usa durante la creación de la base de datos si se omiten los argumentos. |
internal_replication | false | Indica si una tabla Distributed creada con el cluster de esta base de datos Replicated enviará datos a una de las réplicas (la replicación interna significa que las réplicas del cluster realizan la replicación por sí mismas) o a todas las réplicas (sin replicación interna, la tabla Distributed enviará los datos insertados a todas las réplicas) |
<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>
Última modificación el 10 de junio de 2026
