When an LTS-to-LTS ClickHouse upgrade is due and which path is supported
If your self-managed ClickHouse runs an LTS line that is approaching the end of its one-year support window, the upgrade is due now, and the supported path is to move to the next LTS line that is still on the security policy's supported list. LTS releases ship twice a year and are supported for a year after release. The ClickHouse security policy lists versions 26.9, 26.8, 26.7 and 26.3 as currently receiving security updates, and everything else as unsupported. On the releases page, the latest LTS lines are v26.8.29.10-lts and v26.3.53.4-lts, both published October 16, 2026. A team on 26.3 is therefore looking at 26.8 as the next LTS line, and a team already on 26.8 should confirm its own patch level against the latest release shown there.
Before you pick a target, confirm which track you follow. Stable releases ship roughly monthly, the three latest stable releases receive diagnostics and bug fix backports, and the ClickHouse production FAQ recommends stable releases for most production use. LTS is the slower track, so a cluster on LTS and a cluster on stable will reach end of support on different dates. Write down the track, the current version on every shard and replica, and the date your current line leaves the supported list. Then confirm the end-of-support dates with ClickHouse for your line, because the policy page lists supported versions but does not give a schedule. That written inventory is the input to every later decision in this upgrade.
What changes between LTS lines and what each change requires
This table lists the categories of change that matter when moving between LTS lines, what each one affects and the action to take before the upgrade. Use it as a checklist, then pull the exact breaking-change entries for your target release from its changelog. The main takeaway is that the changelog, not this table, is the authority for what breaks in a given release.
| Change category | Impact on your cluster | Action needed before upgrading |
|---|---|---|
| Minor backward-incompatible changes | Queries, settings or behavior that worked on the old LTS line may return different results or fail on the new one. | Read every changelog entry between your current line and the target line, and note each entry that touches queries, settings or defaults. |
| Mandatory query analyzer | Queries that relied on the old query analysis may be rejected or return different results once the analyzer is required. | Run representative queries on the target release in a pre-production environment and review failures in HAVING, JOIN and alias handling. |
| Security support list | Only versions on the published support list receive security updates, so a target outside that list leaves known exposure open. | Confirm the target version appears on the security policy list before scheduling the upgrade, and check it again on the change date. |
| One-year LTS support window | An LTS line is supported for about one year after release, so waiting too long can push you off supported versions. | Plan the next LTS jump before your current line leaves support, and confirm exact support end dates with ClickHouse. |
| Stable release backports | Only the latest stable releases receive diagnostics and bug fix backports, so a stable-track cluster falls behind quickly. | Decide whether your cluster stays on LTS or stable, and align the upgrade cadence with that choice. |
| Replication and Keeper compatibility | Mixed-version replicas and a Keeper ensemble may need checks during the cutover. | Review the replication and Keeper notes in the target release and test a replica restart in staging before production. |
| Pre-production validation | Changelog review alone does not show how your queries and data behave on the new line. | Test on representative data and queries, and record query results and timings for comparison after the upgrade. |
Which upgrade paths stay inside the supported version list
If your cluster runs 26.3 or 26.8, you are on a line that the ClickHouse security policy lists as supported with security updates. Moving from 26.3 to 26.8 is the most common LTS-to-LTS path, and it keeps you inside the supported list. Support lists change as new lines ship, so confirm the path against the policy on the day you schedule the work, not only when the project was first planned.
- Confirm the support list first: Check the security policy for the current supported versions. Only listed versions receive security updates, so a line that drops off the list leaves you exposed.
- Pick the target line on purpose: 26.8 is the LTS line that follows 26.3. Staying on LTS keeps your upgrade cadence slower, which most regulated teams plan around.
- Confirm the exact build on the releases page: Find the patch build you intend to install, such as the published 26.8 LTS build, and read its changelog before the test environment is touched.
- Plan the next jump early: LTS releases are supported for a year after release. Confirm the end of support for your current line and schedule the next move well ahead of it.
Before you choose a target, confirm that your current line is still listed, that the target build appears on the releases page, and that the changelog for every release in between has been read.
Stable releases ship roughly monthly, and the ClickHouse production FAQ says the three latest stable releases receive diagnostics and bug fix backports. The security policy lists 26.9 and 26.7 as supported, so a cluster on either of those stable lines is inside the list today. Stable lines leave the picture faster than LTS lines do, which means a team that falls one or two releases behind can find its version unsupported before its next scheduled maintenance window.
- Check whether your stable line is listed: Versions 26.9 and 26.7 appear in the policy as supported. Any other stable line should be treated as unsupported until the policy says otherwise.
- Watch the stable release cadence: The production FAQ says the three latest stable releases get backports. Older stable lines lose that coverage sooner than LTS lines do.
- Decide whether an LTS target fits: Moving from stable to an LTS line is a change of release track, not only a version bump. Review the changelog for both the stable releases you skip and the LTS build you choose.
- Expect the mandatory analyzer: Query analysis changes in 26.9 and affect HAVING, JOIN and alias behavior. Run your query suite against the target before you commit to a date.
- Pin the target from the releases page: The releases page currently shows v26.9.20.23-stable as the latest stable build, along with the LTS builds v26.8.29.10-lts and v26.3.53.4-lts.
Before you move, confirm that your stable line is still in the policy and that the target build is the one you tested, not the newest build published that week.
The security policy lists only 26.9, 26.8, 26.7 and 26.3 as supported with security updates. Every other version is unsupported, which means no security fixes will be published for it. For an organization under a compliance assessment, running an unsupported version is a finding in its own right, and the upgrade should be treated as a security remediation, not only a routine version change. The path is still a move into a listed version, but the gap between your version and the target usually contains more breaking changes to review.
- Treat the gap as a security item: Document the date your version fell off the list and the reason it remains in production. Auditors will ask for that record.
- Read every changelog in the gap: Review each release between your version and the target, not only the newest one. Breaking changes accumulate across the gap.
- Select the closest supported target: Moving to the nearest supported LTS line is usually the simplest first step, provided that line is on the policy list when you start.
- Take a backup before the first step: Confirm a restorable backup exists and has been test-restored before any binary changes are made.
- Confirm the target against the releases page: A version that is listed today may change. Check the policy and the releases page on the day the change window opens.
Before you start, confirm your current version is absent from the policy, record the gap, and agree with the security owner which listed version you will reach first.
Clusters that are far behind the current supported lines often cannot move to the target in one step without a planned intermediate version or a downtime window. The decision depends on how many releases separate your version from the target, how many breaking changes sit in that range, and whether your replicated cluster can tolerate mixed versions during a rolling upgrade. This topic does not cover those choices in depth, so the points below are only a checklist of what to confirm before you read further.
- Measure the age of your version: Compare your build against the LTS support window and the policy list to see how far behind you are.
- Identify whether an intermediate hop is needed: Some paths may require a stop on a supported line before the target. Confirm the stops with the release notes for each version involved.
- Confirm mixed-version tolerance: A rolling upgrade keeps replicas on different versions for a period. Check the compatibility guidance before assuming that is safe across a wide version gap.
- Compare a downtime upgrade: For some clusters, a planned outage is simpler than several staged moves. Ask your team what downtime the business can accept.
For versions more than a year old, read the dedicated guidance on upgrading ClickHouse versions more than a year old before you commit to a path.
Preparing the cluster before touching a binary
Most failed upgrades are decided before the first package changes. The cards below cover what to protect, what to inventory, where to test and when to decide that a rollback is needed. Work through them in order, because each one produces evidence the next one depends on.
Take a verified backup
Use BACKUP to write a full backup of the databases and tables you cannot lose to local disk, S3-compatible storage or Azure Blob Storage. Replication alone does not protect against human error or corruption, because a bad DROP or a corrupted part is copied to every replica. Record where the backup lives, how long it is kept and who can restore it.
Inventory queries and clients
List the queries, client drivers, settings profiles, users and custom configuration files that touch the cluster, including scheduled jobs and BI tools. Upgrades break most often at the edges, such as a driver that sends an old setting or a dashboard query that relies on alias behavior. Assign an owner to each item so that every change in the changelog can be traced to something the business uses.
Build a representative pre-production cluster
Stand up a pre-production environment with a copy of production schema, a representative slice of data and the real query set. The production FAQ recommends this because minor backward-incompatible changes can occur between releases. Confirm with your own team how much data is enough to exercise your largest joins and aggregations, since a small sample can hide query-plan differences.
Test the restore on a spare cluster
Restore the backup to a spare cluster and confirm that row counts, key queries and user grants match production. The backup documentation warns that a backup never test-restored will probably not restore properly when needed. Repeat the restore test on a schedule, not only before this upgrade, and record the time it took so the rollback plan has a realistic recovery estimate.
Check Keeper and replica health
Confirm that every ClickHouse Keeper node is healthy and that the ensemble has quorum before any restart begins. Check that each replica is in sync with its peers and has no long replication queue, since a recovered replica catches up automatically only if the healthy copies are available. Keep a saved snapshot of these results to compare after each node restarts.
Write the rollback decision point
Before the upgrade starts, write down the conditions that trigger a rollback, who makes that call and the deadline for making it. Include the checks that must pass, such as query results matching the baseline and no growing replication backlog. Confirm whether the target release allows downgrade, because new features or changed on-disk formats can block it, and plan the restore path if it does not.
The upgrade sequence, with checks and rollback points
This sequence moves a self-managed ClickHouse deployment from one LTS line to the next in a controlled order, with a verified backup and a known rollback point before any server changes. Each step closes with a check that tells the team whether to continue, pause or reverse.
Confirm the target version and read the changelog
Confirm the target LTS release is on the supported version list in the ClickHouse security policy, then read the release notes and changelog between your current line and the target. Record every backward-incompatible change that touches your queries, settings, table engines, client drivers or authentication. Output: a written compatibility list signed off by the platform owner. Rollback point: nothing has changed yet, so the decision to proceed is fully reversible.
Rehearse on pre-production with representative data
Restore a recent copy of production data into a pre-production cluster that matches the production topology as closely as practical, then run representative queries, dashboards, ingestion jobs and application client connections against the target version. Compare results and error rates with production on the same workload. Ask your vendor or internal team to confirm which settings differ between environments. Output: a test log showing each query class passed or was fixed, with changes committed to your configuration repository.
Take a backup and prove it restores
Take a full backup with BACKUP to storage that is separate from the cluster being upgraded, then restore it to a spare cluster and run row counts and checksum-style comparisons on key tables. The backup documentation warns that an untested backup will probably not restore when needed, so the restore test is the gate, not the backup job's success status. Output: a restore report with the backup identifier, restore duration observed in your environment, and sign-off. Rollback point: this backup is the fallback if data is damaged during the upgrade.
Upgrade one non-critical replica first
Upgrade a single replica in a non-critical shard, following the rolling procedure described in the rolling zero-downtime upgrade topic. Keep the other replicas on the previous release while this node runs the new binary. Confirm the server starts, joins ClickHouse Keeper, and answers health and version queries. Output: a node reporting the target version with no errors in the server log. Rollback point: the node can still be returned to the previous version if no new-format features have been used yet.
Verify replication catches up after restart
After the upgraded replica restarts, check that its replication queue drains and that it syncs missing data from a healthy replica without manual intervention, as the replication guide describes for recovered replicas. Compare row counts and part counts against a peer replica for the affected tables. Watch the Keeper and replication metrics for stuck entries or repeated errors. Output: matching counts and an empty or shrinking replication queue within an interval you set based on your data volume. If it does not converge, stop and investigate before upgrading anything else.
Proceed through remaining replicas and shards
Upgrade the remaining replicas one at a time, leaving the most business-critical shard for last, and repeat the replication check after each node. Do not run more than one upgrade in progress per shard unless your topology has been tested for it. Keep a running record of each node's version. Output: a version inventory in which every node reports the target release, with replication healthy on all shards. Rollback point narrows: once a shard runs new features or new formats, reverting it becomes harder, as the rollback topic explains.
Run post-upgrade query and client checks
Run the same query suite used in pre-production against production, then check application clients, ingestion pipelines, authentication through LDAP, Kerberos, certificates or JWT, and access control rules such as row policies and quotas. Verify that dashboards and alerts still return expected values. Review the mandatory analyzer impact if you are moving toward 26.9. Output: a signed checklist with each query class and client path marked passed, plus any items deferred with an owner.
Close the change and record the rollback boundary
Document the final version of every node, the backup identifier kept for recovery, the list of new features now in use, and the date the rollback window was judged closed. Remove any temporary compatibility settings only after the applications have been validated, as the compatibility setting topic describes. Output: a closed change record stored with the runbook, with a named owner for monitoring the next release cycle.
How to test queries and decide whether to roll back
Build the test set from what production actually runs, not from queries someone remembers. Pull the query log from the current LTS line (the system.query_log table is the usual source, and its retention depends on how your team configured it) and group statements by normalized shape, user, and dashboard or service that issues them. Keep the most frequent queries, every query behind a scheduled job or regulatory report, and any query that has failed or been rewritten recently. Replay them against a pre-production cluster loaded with a representative copy of the data, on the same replica topology you run in production. The ClickHouse production FAQ recommends a pre-production environment with representative data and queries, and it advises reading the changelog because minor backward-incompatible changes can occur.
For each replayed query, compare two things between the current and target LTS: the result set and the execution time. Result comparison should be exact for deterministic queries, with a documented tolerance for floating-point aggregates and for queries that use now() or unordered LIMIT clauses. Timing comparison should use repeated runs with a warm cache and a cold cache, because a single run hides plan changes. Treat any changed result as a blocker until someone explains it. Treat the analyzer as its own test area: queries using HAVING, JOIN, and column aliases are the ones most likely to change behavior, so work through the sibling topic on preparing for the mandatory analyzer in ClickHouse 26.9 and record each finding against a named query.
Write the rollback plan before the change window opens, and make it specific: which backup you will restore from, who has authority to stop the rollout, and which symptoms trigger a stop. Typical criteria include changed results on business-critical queries, sustained latency regressions against agreed thresholds, errors in ingestion or replication, and failed health checks on replicas. Confirm with the ClickHouse documentation and your own tests whether a downgrade to the previous LTS is possible for your schema and features, because features introduced by the new release can block it, a limit that the rollback topic covers in detail. Take a backup with BACKUP and check that it restores on a spare cluster before you start. The ClickHouse backup documentation warns that an untested backup will probably not restore when needed, so the rollback decision is only as good as that restore test.
What makes an LTS upgrade take longer
How many custom settings and queries change the upgrade effort?
The count of custom settings and queries that touch changed behavior is usually the largest driver of effort. Each LTS line can change defaults, function behavior, and query analysis, so every custom setting and every query pattern that depends on old behavior needs a test. Start by listing overrides in server and user profiles, then run representative queries on the target release and record differences in results and errors. Teams with long-lived ad hoc SQL, many JOINs with aliases, or HAVING clauses that rely on older analysis tend to need the most review time. Read the changelog for each release between your current line and the target, and confirm the items that apply to your settings with the release notes for your exact versions.
Which client applications and drivers need retesting after an upgrade?
Every application, driver, and tool that talks to ClickHouse needs retesting, because the server version and the client library version can both change behavior. Typical examples include application services, BI and dashboard tools, ingestion pipelines, scheduled reports, and client libraries in each language your teams use. Build an inventory of connection methods, query builders, and any code that parses result formats or handles specific error codes. Then test each path against a pre-production cluster loaded with representative data. The effort grows with the number of distinct client stacks and with the number of teams that own them, because each owner must sign off on their own workloads.
Does the number of replicas and shards change how long an upgrade takes?
Yes. A rolling upgrade touches each replica one at a time, so more replicas and shards mean more restarts, more health checks, and more time spent confirming that replicas catch up. The procedure has to respect shard and replica ordering so that every shard keeps at least one healthy copy online. Clusters with many shards also need more coordination in the test plan, including queries that fan out through Distributed tables. Mixed versions exist during the rollout, so the team must plan how long the cluster runs in that state and which checks run at each step. Ask for the exact sequence and checkpoints in the written scope before scheduling a window.
How does data volume affect backup and restore time before an upgrade?
Data volume sets how long a full backup, and a test restore, takes. Before an upgrade, you should take a backup you can restore, and the backup window scales with the amount of data, the storage target, and network throughput. A backup that has never been restored is not a tested backup, so the restore test also needs time on a spare cluster. Incremental backups shorten repeated runs but still require a verified base. Ask the engineers to measure restore time on a copy of production data, then use that measurement to size the change window. The storage target you choose, whether local disk, S3-compatible storage, or Azure Blob Storage, will also set the pace.
Why does ClickHouse Keeper topology change the upgrade plan?
ClickHouse Keeper coordinates replicated tables, so its topology decides how safely the servers can restart. The replication documentation recommends at least three Keeper nodes, on dedicated hosts in production. A rolling ClickHouse upgrade must keep Keeper quorum available, which means the team needs to know how many Keeper nodes it has, where they run, and whether they share hosts with ClickHouse servers. Single-node or co-located Keeper setups add risk and often require a longer plan with extra checks. Verify the Keeper layout before setting the schedule. If Keeper must be upgraded separately, that work adds its own steps and checks.
What access control and authentication settings need checking after an upgrade?
Users, roles, row policies, settings profiles, quotas, and external authenticators all need re-verification after an upgrade, because a changed default or a changed authenticator behavior can lock out users or widen access. Check that the default user is still restricted, that roles grant the intended privileges, and that row policies still filter as expected. If you use LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator, or JWT authentication, test each login path with real identities in a pre-production environment. Plan the review as a checklist that security and platform owners sign off together. The effort depends on how many users, groups, and authentication methods your environment defines.
Can our own team run an LTS upgrade, and what would a partner add?
A team with ClickHouse operations experience can run an LTS upgrade internally, provided it has a pre-production cluster with representative data, a tested backup and restore path, and time to review changelogs and client stacks. The work that usually takes longest is not the upgrade command itself but the inventory, the test cycle, and the sign-offs. An external partner can take on scope definition, the test matrix, runbooks, and verification evidence under a written, fixed scope. Ask any provider to list what is included, which environments they will use, who owns the rollback decision, and which items remain with your team. DeployOpen implements, hardens, backs up, upgrades, documents, and supports self-hosted platforms in your own infrastructure, and quotes follow from the written scope.
Which upgrade tasks should I ask a provider to quote separately?
Ask for separate line items for the discovery inventory, the changelog review, the test environment, the data restore test, the rolling upgrade itself, and post-upgrade verification. Also ask for each client stack and each authentication method to be listed, because those drive most of the variation. Request a clear statement of which items are one-time and which recur, such as ongoing support or a retainer for later upgrades. Confirm what evidence you will receive at the end, such as test results and checklists. Quotes depend on the written scope, so the more precisely your inventory is defined, the more comparable the proposals will be.
How DeployOpen scopes and delivers a ClickHouse upgrade
DeployOpen approaches an LTS-to-LTS ClickHouse upgrade as a written, fixed-scope piece of work: the version path, the breaking changes that apply to your queries, and the test evidence you need before production are agreed up front. Each step produces documented deliverables your team keeps, so the upgrade can be repeated and audited later.
How we scope
- Inventory your current ClickHouse version, cluster topology, Keeper ensemble and the applications that query it.
- Map the changelog entries between your current LTS line and the target line against the features and queries you use.
- Agree the written scope, deliverables and timeline before work starts, since most engagements are fixed-scope.
- Confirm the target version is on the supported list in the ClickHouse security policy at the time of the upgrade.
How we build
- Stand up a pre-production cluster with representative data volumes, schemas and query sets from your workloads.
- Run the target release against recorded production queries and compare results, errors and resource use with the current version.
- Document each breaking change found, with the query, the affected application and the fix or setting chosen.
- Rehearse the upgrade runbook, including backup creation and a restore test on a spare cluster before the production window.
How we hand over
- Deliver the upgrade runbook with ordered steps, checkpoints, health checks and go or no-go criteria.
- Provide the test evidence, including query comparison results and the list of resolved incompatibilities.
- Hand over the rollback plan, stating which backups exist and the point after which downgrade is no longer possible.
- Walk your operators through the post-upgrade checks and the monitoring signals to watch in the first days.
How we support
- Support the production window and the first post-upgrade period as part of the written scope.
- Offer ongoing support, upgrades and continuous testing as a retainer for the next LTS line.
- Ask your team to confirm the support window for each version in their own environment before planning the next move.
- Keep the runbook and test suite current so the next LTS upgrade starts from documented evidence.
