Upgrading ClickHouse LTS Releases: From 24.x and 25.x to 26.3 or 26.8 LTS, Changelog Checks, the compatibility Setting and Rolling Replicas

The short answer

ClickHouse ships a stable release roughly every month and an LTS release twice a year, in March and August. The production FAQ says the three latest stable releases get bug fix backports and each LTS release is supported for a year after its first release. On 5 October 2026 the project's SECURITY.md lists 26.9, 26.8, 26.7 and 26.3 as supported for security updates. Every 25.x release is marked unsupported, including the 25.3 and 25.8 LTS lines, and so is everything older.

The two upgrade targets that stay supported longest are therefore 26.8 LTS, released on 27 August 2026, and 26.3 LTS, released on 26 March 2026. ClickHouse's self-managed upgrade guide supports zero-downtime rolling upgrades of replicas, but only between versions less than about a year apart. A cluster on 24.x needs intermediate stops, or a full-downtime upgrade. The ClickHouse end-of-life tracker has every line.

LTS releases and their status

Release dates come from the ClickHouse changelogs and status from SECURITY.md. Under the one-year policy, 26.3 drops out around March 2027 and 26.8 around August 2027. Our recommendation is 26.8 for a cluster that upgrades once a year, since it buys the longest window.

How far you can jump

The upgrade guide is specific about mixed versions. ClickHouse tries to keep a one-year compatibility window, which includes two LTS versions, so two versions should work together in a cluster if they are less than a year apart or have fewer than two LTS releases between them. Even then, it recommends getting every member onto the same version quickly, because distributed queries can slow down and background ReplicatedMergeTree operations can hit retriable errors.

Beyond a year, the guide says never to mix versions: the cluster may not work, queries may fail with arbitrary errors and a downgrade may become impossible. For a larger gap it gives two options: upgrade with downtime, stopping and upgrading every server together, or go through an intermediate version less than a year newer.

Each step stays within the window. We include 26.3 on the way from 25.x because of the insert deduplication change described below. Use the latest patch release of each intermediate line.

Read the changelogs backwards

The guide's plan starts with reading the changelogs for breaking changes, going back from the target release to the one you run, and splitting them into changes you can make before the upgrade and changes you can only make after. Each release has a "Backward Incompatible Change" section, and between 25.1 and 26.8 those sections hold more than 170 entries. These are among the ones most likely to matter on the way to 26.8:

One change after 26.8 is worth knowing now. In 26.9 the analyzer can no longer be disabled and compatibility no longer reverts it; the analyzer has been the default since 24.3. 26.8 still lets you turn it off, so any queries that only work with enable_analyzer = 0 need fixing before the next upgrade after 26.8.

The compatibility setting

compatibility makes ClickHouse use the default settings of an earlier version, for example compatibility = '25.8'. Settings you have set explicitly are left alone, and the setting never applies a value your settings profile constraints would forbid. system.settings_changes shows which defaults changed in which version.

Our recommendation: set compatibility to the version you are leaving in the default settings profile before the first server moves, upgrade, then remove it once tests pass. That separates the binary upgrade from the behaviour changes. It does not cover everything. Server settings, removed features and on-disk formats are outside it, and, as 26.9 shows, some changes are deliberately not revertible.

Insert deduplication across the upgrade

Replicated tables deduplicate retried inserts through hashes stored in ZooKeeper or Keeper. 26.2 added the server setting insert_deduplication_version, and 26.3 LTS defaults it to compatible_double_hashes, which writes both the legacy and the new unified hash. 26.6 changed the default to the unified hash, and from 26.7 only the unified hash exists. The 26.7 notes say that a version using a legacy value should first run a release that supports compatible_double_hashes for at least replicated_deduplication_window_seconds, one hour by default. The notes also say to ignore this if you never set the setting.

Our recommendation for clusters on 25.x whose ingestion relies on insert retries being deduplicated: stop on 26.3 and let it run past the deduplication window before moving to 26.8. That costs one extra roll and closes a window in which a retried insert could be written twice.

Replicated tables, Keeper and ZooKeeper

The guide says to upgrade ClickHouse server separately from ClickHouse Keeper or ZooKeeper. Unless Keeper or ZooKeeper needs a security fix, it does not need upgrading at the same time, and Keeper must be stable while the servers roll, so finish the server upgrade before touching coordination. Two consequences:

• Check the coordination service on its own terms. A ZooKeeper ensemble on 3.4 to 3.7 is end of life whatever ClickHouse version sits on top. Keeper versions older than 23.9 hit the 25.10 async replication change above.
• Moving from ZooKeeper to Keeper is a separate project. It needs a maintenance window and a data conversion. Our ClickHouse Keeper vs ZooKeeper guide covers it, and the ClickHouse and ZooKeeper page covers versions.

Rolling upgrade of replicas

The guide's zero-downtime plan:

1. Make sure configuration overrides live in /etc/clickhouse-server/config.d/ and not in config.xml, which the package upgrade can overwrite.
2. Read the changelogs back from the target to your version, make the changes that can be made now, and list the ones for afterwards.
3. Pick one or more replicas in each shard to keep serving while the others are upgraded.
4. On each of the other replicas, one at a time: stop the server, upgrade it, start it, and wait for the Keeper messages to show the system is stable.
5. Check the Keeper and ClickHouse logs for errors.
6. Upgrade the replicas kept back in step 3.
7. Make the post-upgrade changes from step 2.

While versions are mixed, replicas may log CHECKSUM_DOESNT_MATCH from MergeFromLogEntryTask, because a merge on a new replica is not byte-identical to one on an old replica. The guide says this is expected and stops once all replicas match. Several servers can be upgraded at once, as long as all replicas of a shard are never offline together. If you use experimental features, the guide recommends testing them on a separate server on the target version first, since their compatibility can break at any release.

Test plan

• Run the upgrade on a pre-production cluster with production-like replication, distributed tables and materialized views, as the production FAQ recommends.
• Replay a sample of real queries before and after, and compare results and timings, with and without compatibility.
• Insert through every ingestion path, including Kafka engines and retries, and check row counts for duplicates and losses.
• Watch system.replication_queue and merges until the queues drain after each replica.
• Restart a replica mid-insert and confirm it catches up.
• Check dictionaries, especially library sources, and anything using Object or removed codecs.

Downgrades and rollback

The guide allows a downgrade to a version less than a year old only if you have not started using new features, and says the downgrade will not work once they are used. Newer releases also write data parts older ones cannot read: String parts from 25.11 onward are unreadable before 25.10, and JSON parts from 25.12 onward unreadable before 25.8. The changelog gives the settings that keep a downgrade possible: compatibility set to the previous version, or dynamic_serialization_version='v2' and object_serialization_version='v2' for JSON, and serialization_info_version set to basic with string_serialization_version set to single_stream in the server's merge_tree section for strings.

Our recommendation: set those before the first replica moves and keep them until the rollback window closes, keep the previous packages on every host, and take a backup before each hop. A cluster that has crossed a format boundary without them can only go back by restoring that backup.

If you cannot upgrade yet

Analytics clusters often run on a release that has quietly left the window: a 24.8 or 25.3 LTS chosen for stability, or a stable release nobody revisited. OSSeva ships patched, signed builds for ClickHouse releases outside the community window, including 24.x and older, all of 25.x and the 26.x releases that have dropped out, with the same on-disk format, and patched ZooKeeper 3.4 to 3.7 builds for the ensemble under replicated tables, delivered as deb, RPM, Docker and tarballs. Assure adds a replication, sharding and coordination topology review, a ZooKeeper ACL, SASL and exposure audit, a ClickHouse Keeper migration plan with a tested runbook, a SOC 2 and HIPAA attestation package with VEX for scanner findings and an upgrade plan to a supported stable or LTS release. Operate adds 24/7 replication queue, merge and Keeper quorum monitoring, a 15-minute P1 response, a named senior ClickHouse engineer, the ZooKeeper to Keeper cutover in your maintenance window, and release upgrades executed shard by shard. See ClickHouse support and ClickHouse extended support.

Common questions

Which ClickHouse LTS versions are supported?

On 5 October 2026, 26.3 and 26.8. SECURITY.md also lists the stable releases 26.9 and 26.7. Every 25.x release is unsupported.

Can I upgrade ClickHouse 24.8 straight to 26.8?

Not as a rolling upgrade; the versions are two years apart. Either upgrade every server together with downtime, or go through intermediate versions less than a year apart.

Do I need to upgrade ClickHouse Keeper at the same time?

No. ClickHouse recommends upgrading the servers first and Keeper separately, unless Keeper needs a security fix. Keeper older than 23.9 needs a step to 23.9 or later, or async replication turned off, before moving to 25.10 or later.

Can I downgrade after upgrading?

Only to a version less than a year old, before you use new features, and only if no data parts were written in a format the older version cannot read. Set the serialization or compatibility settings before the upgrade if you want to keep that option.