ClickHouse Versions: Release Channels, LTS, Stable, and Testing

ClickHouse releases frequently. New feature builds land roughly every month, maintenance backports every few weeks, and the wider ecosystem (drivers, operators, sidecars) usually has to catch up after every minor jump. Choosing a version is less about chasing the latest tag and more about picking a release channel that matches your tolerance for change. This guide explains how ClickHouse versions are numbered, what the channels mean, and how to think about upgrades on a production cluster.

Version Number Format

ClickHouse versions look like 21.3.10.1-lts or 24.8.5.115. The fields, left to right, are:

Example: 24.8.5.115 is the fifth maintenance release of the 8th feature release of 2024, build 115. When the maintenance number increases, the change is bugfix-only: no new features, no schema-breaking behavior.

The Type suffix is the one users have to read carefully because the same YY.Feature.Maintenance tag can exist in multiple channels with different stability levels.

Release Channels

testing

The newest builds, cut from master. New features land first. Bugs land first too. Useful for evaluating upcoming functionality or filing issues, not for production unless you have a strong reason and a rollback plan.

prestable

A release candidate state. The build has passed internal CI but has not been declared stable. Used to surface regressions before promoting to stable.

stable

The default channel for most production deployments. New stable releases are cut roughly monthly, and the three latest stable releases receive diagnostics and bugfix backports.

lts (Long Term Support)

Selected feature releases marked for extended bugfix backports. ClickHouse cuts two LTS releases per year, each supported for a year after release. The intent is to give operators a version that receives fixes for many months without forcing a feature upgrade.

The maintenance number on an LTS release climbs over time as backports land. 21.3.10.1-lts means "the 21.3 LTS line, tenth maintenance release."

Vendor-stabilized builds

Several vendors maintain their own stabilized builds of ClickHouse: extra QA, documented upgrade paths, security backports, and longer support windows. These typically lag the upstream feature releases by some months and are aimed at conservative production environments. Pick one when the operational guarantees matter more than the latest features.

Picking a Version

A practical decision tree:

1. Greenfield deployment. Start with the latest stable release of the previous feature line. You get the features you need, you skip the bugs of the just-cut release, and you can move to the current line a few months later.
2. Existing production on a feature release. Stay on that line and apply maintenance releases as they come out. They are bugfix-only and rarely break anything.
3. Long-lived production cluster with limited upgrade windows. Track an LTS line or a vendor-stabilized build. Plan a feature upgrade when the LTS support window ends.
4. Need a feature from the latest release. Test on staging first. Have a rollback plan: ClickHouse downgrades within a feature release are usually fine; across feature releases they often are not because of system table schema changes.

Avoid running anything older than the current LTS or the last two stable feature releases. ClickHouse moves fast: critical bugfixes accumulate, and older builds become harder to support.

Upgrade Cadence

A reasonable rhythm:

• Maintenance upgrades: apply within days or a couple of weeks of release for the line you are tracking. They are low-risk.
• Feature upgrades: every 3 to 6 months. Read the changelog for breaking changes (Backward Incompatible Change sections). Test on staging with a representative workload, including any materialized views, dictionaries, and Kafka engines.
• Major year transitions: when moving to a new YY, plan a longer test window. Yearly transitions sometimes coincide with internal data format changes that affect on-disk parts and replication.

Reading the Changelog Before Upgrading

The official changelog groups entries by feature release and clearly marks:

• Backward Incompatible Changes: behavior or syntax changes that may break existing queries or schemas.
• New Features: additions, usually opt-in.
• Performance Improvements: usually safe but occasionally affect query plans.
• Bug Fixes: explicit bugfixes with PR references.
• Build/Testing/Packaging: internal changes, low risk for operators.

Before a feature upgrade, read every Backward Incompatible Change between your current version and the target. Many ClickHouse upgrade incidents come from a single skipped changelog entry: a setting changed default, a function changed return type, a system table column renamed.

What Changes Between Channels

A common misconception: testing and stable carry different code. They do not. The build is the same source tree at a given tag; what changes is the confidence that the tag is production-grade. A testing build of 24.10.1.1 and a future stable build of 24.10.5.x differ only in the patches landed in between (and the QA history).

This is why version pinning to a specific maintenance release is the safe pattern. Pinning to latest of any channel introduces drift you cannot easily reproduce.

Common Pitfalls

• Mixed versions across replicas. ClickHouse tolerates short version skew during a rolling upgrade but not indefinitely. Aggregate function state formats and replication protocol details have changed between versions. Plan to finish a cluster upgrade in one window.
• Skipping maintenance releases. Maintenance releases bundle real bugfixes. Running an older maintenance because "we already upgraded to this feature release" leaves known issues unfixed.
• Upgrading the server before drivers. Some driver versions assume specific server behavior. Upgrade drivers in lockstep, especially for the native TCP protocol.
• Not testing materialized views and dictionaries. Changes in function semantics or aggregate state formats most often break MVs and dictionaries first because they are the densest place where computed values touch storage.

How Pulse Helps With Version Management

A ClickHouse fleet on multiple versions is the operational reality at most companies. Pulse tracks the version of every node in every cluster, flags clusters running unsupported or pre-LTS builds, and watches the upstream changelog for issues that match the workload patterns it sees in your queries. Connect your cluster to Pulse and stop discovering version-specific bugs the hard way.

Frequently Asked Questions

Q: How do I check the version of a running ClickHouse?

SELECT version();

Or from the shell: clickhouse-server --version and clickhouse-client --version.

Q: What is the difference between lts and stable?

Both are production-grade. lts is a specifically nominated feature release that receives bugfix backports for an extended window. stable is the current stable feature release. Use LTS if your operational policy requires a long support window without feature upgrades.

Q: Can I downgrade ClickHouse?

Within the same feature release (maintenance to earlier maintenance), usually yes. Across feature releases, often no, because data file formats and system table schemas may have evolved. Test downgrades on staging if you need this capability.

Q: How long is a feature release supported?

The community supports the three latest stable feature releases with diagnostics and bugfix backports. LTS releases are supported for a year after their initial release. Vendor builds publish their own support matrices.

Q: Should I run testing in production?

Generally no. It is useful for evaluating new features or pre-validating an upcoming stable. Production should run stable or LTS.

Q: Is it safe to skip feature releases when upgrading?

You can upgrade across multiple feature releases at once, but each one you skip is a changelog you have not read. Read every Backward Incompatible Change entry between source and target. Larger jumps also accumulate more risk in materialized views and aggregate states.