ClickHouse em cluster¶
Topologia de referência: 2 shards × 2 réplicas + 3 ClickHouse Keeper
(docker-compose.cluster.yml, arquivos em deploy/clickhouse/cluster/).
flowchart LR
APP[api / ingestor / engine<br/>QV_CH_HOST=ch-s1r1,ch-s1r2,ch-s2r1,ch-s2r2<br/>QV_CH_CLUSTER=qv_cluster]
subgraph C["qv_cluster"]
S1R1[(ch-s1r1)] <--> S1R2[(ch-s1r2)]
S2R1[(ch-s2r1)] <--> S2R2[(ch-s2r2)]
end
K1[ch-keeper-1] --- K2[ch-keeper-2] --- K3[ch-keeper-3]
APP --> S1R1 & S1R2 & S2R1 & S2R2
C -. "replicação e DDL distribuído" .- K1
make gen-env # inclui CLICKHOUSE_INTERSERVER_PASSWORD
make up CLUSTER=1 # docker compose -f docker-compose.yml -f docker-compose.cluster.yml up -d
Este arquivo sobe a topologia em um host (validação/laboratório). Para os nós ClickHouse em
servidores distintos, com Keeper, DNS e migração do histórico feitos pelo instalador, veja
Cluster distribuído (./install.sh com topology: cluster ou ./install.sh expand).
Como o schema é criado (modo nativo)¶
Com QV_CH_CLUSTER=qv_cluster, o próprio backend (common/tsdb.py::schema_statements) cria, no
boot, com DDL ON CLUSTER idempotente:
| Objeto | Banco | Engine |
|---|---|---|
metrics, health_history |
qv_local |
ReplicatedMergeTree |
metrics_1h, metrics_1d, metrics_latest |
qv_local |
ReplicatedAggregatingMergeTree |
metrics_1h_mv, metrics_1d_mv, metrics_latest_mv |
qv_local |
materialized views locais (cada shard calcula os rollups das suas entidades) |
metrics, metrics_1h, metrics_1d, metrics_latest, health_history |
qv |
Distributed(qv_cluster, qv_local, <tabela>, cityHash64(entity_id)) |
- A aplicação continua usando
qv.*. Leituras e escritas passam pelas tabelasDistributed, e qualquer nó atende o cluster inteiro. - O sharding por
entity_idmantém cada série inteira em um shard, então rollups,argMaxe percentis são exatos. - As engines
Replicated*usamdefault_replica_path/default_replica_namecom as macros{shard}/{replica}definidas por variáveis de ambiente de cada nó (CH_SHARD,CH_REPLICA). - Alterar a retenção na GUI executa
ALTER TABLE qv_local.<t> ON CLUSTER qv_cluster MODIFY TTL …. - Failover de conexão:
QV_CH_HOSTaceita uma lista. Em erro de conexão, o cliente passa para o próximo host (balanceadores como chproxy, HAProxy ou um Service k8s também funcionam). - A tela Sistema soma
system.partsde todas as réplicas (clusterAllReplicas).
| Porta | Uso |
|---|---|
| 8123 | HTTP (aplicação) |
| 9000 | nativo (entre nós e Distributed) |
| 9009 | interserver (replicação), com credenciais interserver |
| 9181 / 9234 / 9182 | Keeper cliente / Raft / readiness |
Estado de validação
O DDL de cluster foi verificado no motor do ClickHouse via chdb (com as engines replicadas/distribuídas substituídas por equivalentes locais). Não houve teste em um cluster real nesta versão. Faça um ensaio (inserção, consulta, perda de uma réplica, troca de TTL) antes de produção. Em produção, coloque cada nó em um servidor físico distinto (anti-afinidade).
Backup em cluster¶
O script de backup de host único não cobre o cluster (o site.yml não agenda backup quando
quantix_clickhouse_cluster é verdadeiro). Use o backup nativo distribuído: