Pular para conteúdo

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 tabelas Distributed, e qualquer nó atende o cluster inteiro.
  • O sharding por entity_id mantém cada série inteira em um shard, então rollups, argMax e percentis são exatos.
  • As engines Replicated* usam default_replica_path/default_replica_name com 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_HOST aceita 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.parts de 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:

BACKUP DATABASE qv_local ON CLUSTER qv_cluster TO S3('https://s3.empresa.local/quantix/qv-AAAAMMDD', '<key>', '<secret>');