Перейти к основному содержанию

​
Обзор обновления ClickHouse

Этот документ содержит:
  • общие рекомендации
  • рекомендуемый план
  • особенности обновления бинарных файлов в используемых вами системах

​
Общие рекомендации

Эти примечания помогут вам с планированием и понять, почему далее в документе мы даем именно такие рекомендации.

​
Обновляйте сервер ClickHouse отдельно от ClickHouse Keeper или ZooKeeper

Если для ClickHouse Keeper или Apache ZooKeeper не требуется исправление безопасности, обновлять Keeper вместе с сервером ClickHouse не нужно. Во время обновления важно сохранять стабильность Keeper, поэтому сначала полностью завершите обновление сервера ClickHouse и только затем при необходимости обновляйте Keeper.

​
Минорные версии следует обновлять как можно чаще

Настоятельно рекомендуется всегда обновляться до новейшей минорной версии сразу после ее выхода. Минорные релизы не содержат несовместимых изменений, но включают важные исправления ошибок (а также могут содержать исправления, связанные с безопасностью).

​
Тестируйте экспериментальные возможности на отдельном сервере ClickHouse с целевой версией

Совместимость экспериментальных возможностей может нарушиться в любой момент и самым непредсказуемым образом. Если вы используете экспериментальные возможности, следите за журналами изменений и рассмотрите возможность развернуть отдельный сервер ClickHouse с установленной целевой версией, чтобы протестировать их там.

​
Понижение версии

Если после обновления окажется, что новая версия несовместима с какой-либо возможностью, от которой вы зависите, вы можете понизить версию до одной из недавних версий (не старше одного года), если еще не начали использовать новые возможности. Как только новые возможности будут задействованы, понижение версии уже не сработает.

​
Несколько версий сервера ClickHouse в кластере

Мы стараемся поддерживать окно совместимости сроком в один год (включая 2 LTS-версии). Это означает, что любые две версии должны работать вместе в кластере, если разница между ними составляет менее одного года (или если между ними меньше двух LTS-версий). Однако рекомендуется как можно быстрее обновить все узлы кластера до одной и той же версии, так как возможны некоторые незначительные проблемы (например, замедление распределённых запросов, временные ошибки с возможностью повтора в некоторых фоновых операциях ReplicatedMergeTree и т. д.). Мы никогда не рекомендуем запускать разные версии в одном кластере, если даты их выпуска отличаются более чем на один год. Хотя мы не ожидаем потери данных, кластер может стать непригодным к использованию. Если разница между версиями превышает один год, возможны следующие проблемы:
  • кластер может не работать
  • некоторые (или даже все) запросы могут завершаться произвольными ошибками
  • в журналах могут появляться произвольные ошибки/предупреждения
  • может оказаться невозможно понизить версию

​
Поэтапные обновления

Если разница между текущей и целевой версиями превышает один год, рекомендуется выбрать один из следующих вариантов:
  • Выполнить обновление с простоем (остановить все серверы, обновить все серверы, запустить все серверы).
  • Либо выполнить обновление через промежуточную версию (версию, выпущенную менее чем через год после текущей версии).
Ниже приведены рекомендуемые шаги для обновления ClickHouse без простоя:
  1. Убедитесь, что изменения конфигурации вносятся не в файл /etc/clickhouse-server/config.xml по умолчанию, а в /etc/clickhouse-server/config.d/, поскольку во время обновления файл /etc/clickhouse-server/config.xml может быть перезаписан.
  2. Просмотрите changelogs на предмет несовместимых изменений (от целевого релиза до релиза, который вы используете сейчас).
  3. Внесите все изменения, указанные в списке несовместимых изменений, которые можно сделать до обновления, и составьте список изменений, которые потребуется внести после обновления.
  4. Определите одну или несколько реплик для каждого сегмента, которые останутся в работе, пока остальные реплики каждого сегмента будут обновляться.
  5. На репликах, которые будут обновляться, по одной за раз:
  • остановите сервер ClickHouse
  • обновите сервер до целевой версии
  • запустите сервер ClickHouse
  • дождитесь, пока сообщения Keeper покажут, что система стабильна
  • переходите к следующей реплике6. Проверьте наличие ошибок в журнале Keeper и журнале ClickHouse
  1. Обновите реплики, определённые на шаге 4, до новой версии
  2. Обратитесь к списку изменений, составленному на шагах 1–3, и внесите изменения, которые нужно выполнить после обновления.
Это сообщение об ошибке ожидаемо, когда в реплицируемой среде одновременно работают несколько версий ClickHouse. Вы перестанете видеть такие сообщения, когда все реплики будут обновлены до одной и той же версии.
MergeFromLogEntryTask: Code: 40. DB::Exception: Checksums of parts don't match:
hash of uncompressed files doesn't match. (CHECKSUM_DOESNT_MATCH)  Data after merge is not
byte-identical to data on another replicas.

​
Процесс обновления бинарного файла сервера ClickHouse

Если ClickHouse был установлен из пакетов deb, выполните на сервере следующие команды: 
$ sudo apt-get update
$ sudo apt-get install clickhouse-client clickhouse-server
$ sudo service clickhouse-server restart
Если вы установили ClickHouse не с помощью рекомендуемых пакетов deb, используйте подходящий способ обновления.
Вы можете обновлять несколько серверов одновременно, если не допускаете ситуации, когда все реплики одного сегмента одновременно находятся офлайн.
Обновление ClickHouse со старой версии до конкретной версии: Например: xx.yy.a.b — текущая стабильная версия. Последнюю стабильную версию можно найти здесь 
$ sudo apt-get update
$ sudo apt-get install clickhouse-server=xx.yy.a.b clickhouse-client=xx.yy.a.b clickhouse-common-static=xx.yy.a.b
$ sudo service clickhouse-server restart
Последнее изменение 10 июня 2026 г.