Pular para o conteúdo principal

​
Visão geral da atualização do ClickHouse

Este documento contém:
  • diretrizes gerais
  • um plano recomendado
  • detalhes específicos para atualizar os binários em seus sistemas

​
Diretrizes gerais

Estas notas devem ajudar você no planejamento e a entender por que fazemos as recomendações apresentadas mais adiante neste documento.

​
Atualize o servidor ClickHouse separadamente do ClickHouse Keeper ou ZooKeeper

A menos que seja necessária alguma correção de segurança no ClickHouse Keeper ou no Apache ZooKeeper, não é necessário atualizar o Keeper ao atualizar o servidor ClickHouse. A estabilidade do Keeper é essencial durante o processo de atualização; portanto, conclua as atualizações do servidor ClickHouse antes de considerar uma atualização do Keeper.

​
Atualizações de versões menores devem ser adotadas com frequência

É altamente recomendável sempre atualizar para a versão menor mais recente assim que ela for lançada. Os lançamentos menores não incluem mudanças incompatíveis, mas trazem correções de bugs importantes (e podem incluir correções de segurança).

​
Teste recursos experimentais em um servidor ClickHouse separado executando a versão de destino

A compatibilidade dos recursos experimentais pode ser perdida a qualquer momento e de várias maneiras. Se você estiver usando recursos experimentais, verifique os changelogs e considere configurar um servidor ClickHouse separado com a versão de destino instalada para testar ali o uso desses recursos experimentais.

​
Downgrades

Se você fizer upgrade e depois perceber que a nova versão não é compatível com algum recurso de que você depende, talvez seja possível fazer downgrade para uma versão recente (com menos de um ano), desde que você ainda não tenha começado a usar nenhum dos novos recursos. Depois que esses novos recursos forem usados, o downgrade não funcionará.

​
Múltiplas versões do servidor ClickHouse em um cluster

Nos esforçamos para manter uma janela de compatibilidade de um ano (que inclui 2 versões LTS). Isso significa que quaisquer duas versões devem conseguir funcionar juntas em um cluster se a diferença entre elas for inferior a um ano (ou se houver menos de duas versões LTS entre elas). No entanto, recomenda-se atualizar todos os membros de um cluster para a mesma versão o mais rápido possível, pois podem ocorrer alguns problemas menores (como lentidão em consultas distribuídas, erros passíveis de nova tentativa em algumas operações em segundo plano no ReplicatedMergeTree etc.). Nunca recomendamos executar versões diferentes no mesmo cluster quando as datas de lançamento tiverem mais de um ano de diferença. Embora não esperemos perda de dados, o cluster pode se tornar inutilizável. Os problemas que você deve esperar caso haja mais de um ano de diferença entre as versões incluem:
  • o cluster pode não funcionar
  • algumas (ou até mesmo todas) consultas podem falhar com erros aleatórios
  • erros/avisos aleatórios podem aparecer nos logs
  • pode ser impossível fazer downgrade

​
Atualizações incrementais

Se a diferença entre a versão atual e a versão de destino for superior a um ano, recomenda-se:
  • Atualizar com indisponibilidade (parar todos os servidores, atualizar todos os servidores, iniciar todos os servidores).
  • Ou atualizar por meio de uma versão intermediária (uma versão com menos de um ano de diferença em relação à versão atual).
Estas são as etapas recomendadas para uma atualização do ClickHouse sem indisponibilidade:
  1. Certifique-se de que suas alterações de configuração não estejam no arquivo padrão /etc/clickhouse-server/config.xml e, em vez disso, estejam em /etc/clickhouse-server/config.d/, pois /etc/clickhouse-server/config.xml pode ser sobrescrito durante uma atualização.
  2. Leia os changelogs para verificar alterações incompatíveis (do lançamento de destino até o lançamento que você está usando atualmente, retrocedendo entre as versões).
  3. Faça, antes da atualização, todas as alterações identificadas nas mudanças incompatíveis que puderem ser aplicadas e liste as alterações que precisarão ser feitas após a atualização.
  4. Identifique uma ou mais réplicas de cada shard para mantê-las em funcionamento enquanto as demais réplicas de cada shard são atualizadas.
  5. Nas réplicas que serão atualizadas, uma de cada vez:
  • desligue o servidor ClickHouse
  • atualize o servidor para a versão de destino
  • inicie o servidor ClickHouse novamente
  • aguarde até que as mensagens do Keeper indiquem que o sistema está estável
  • prossiga para a próxima réplica6. Verifique se há erros no log do Keeper e no log do ClickHouse
  1. Atualize as réplicas identificadas na etapa 4 para a nova versão
  2. Consulte a lista de alterações das etapas 1 a 3 e faça as alterações que precisam ser aplicadas após a atualização.
Essa mensagem de erro é esperada quando há várias versões do ClickHouse em execução em um ambiente replicado. Você deixará de vê-la quando todas as réplicas forem atualizadas para a mesma versão.

​
Processo de atualização do binário do servidor ClickHouse

Se o ClickHouse foi instalado a partir de pacotes deb, execute os seguintes comandos no servidor:
Se você instalou o ClickHouse por um método diferente dos pacotes deb recomendados, use o método de atualização apropriado.
Você pode atualizar vários servidores ao mesmo tempo, desde que não haja nenhum momento em que todas as réplicas de um shard fiquem offline.
A atualização de uma versão mais antiga do ClickHouse para uma versão específica: Por exemplo: xx.yy.a.b é uma versão estável atual. A versão estável mais recente pode ser encontrada aqui
Última modificação em 12 de junho de 2026