Upgrading Self-Managed ClickHouse in 2026: Breaking Changes from 26.3 LTS to 26.8 LTS and 26.9

Self-managed ClickHouse shipped two LTS releases in 2026, 26.3 in March and 26.8 in August, followed by 26.9 in September. Together they carry an unusually long list of backward-incompatible changes. Some only change a default. Others stop a server from starting if an obsolete object or setting is still present.

This article groups those changes by the kind of risk they create, then sets out an upgrade procedure. It covers open-source ClickHouse that you operate yourself, under the Apache License 2.0. ClickHouse Cloud manages upgrades for you and is a separate route.

Release lines on the research date

The 2026 changelog lists these releases, and the project’s security policy lists which versions receive security updates:

Release	Date	Type	Security updates (SECURITY.md)
26.9	2026-09-21	Stable	Supported
26.8	2026-08-27	LTS	Supported
26.7	2026-07-22	Stable	Supported
26.4 to 26.6	April to June 2026	Stable	Not supported
26.3	2026-03-26	LTS	Supported
25.x and earlier			Not supported

Two consequences follow. Any cluster still on a 25.x release is outside the security-update list. And a team on 26.3 LTS should plan its move to 26.8 LTS now, rather than when 26.3 leaves the list. The self-managed upgrade guide describes a compatibility window of about one year, which includes two LTS versions, so 26.3 to 26.8 is a supported jump for a rolling upgrade.

Changes that can stop a server from starting

These deserve the most attention, because they turn a routine restart into an outage. Each comes from the changelog entries for the version shown.

• Window views (26.9). The experimental WINDOW VIEW feature, the WATCH statement and the windowID function are removed. A server that finds a window view in its metadata fails to start. Drop window views before upgrading.
• CatBoost (26.9). catboostEvaluate, system.models and SYSTEM RELOAD MODEL(S) are removed. Revoke SYSTEM RELOAD MODEL from all users and roles first, because an access entity that still mentions the privilege cannot be parsed on startup. Let any pending ON CLUSTER entries for it drain.
• WasmEdge (26.9). A server configured with webassembly_udf_engine = 'wasmedge' will not start. Remove the setting or set it to wasmtime.
• Insert deduplication (26.6 and 26.7). 26.6 changes the default of insert_deduplication_version to new_unified_hash. From 26.7 the unified hash is always used, and the server refuses to start if the setting holds a legacy value.
• Nullable tuples (26.9). Nullable(Tuple(...)) becomes generally available and on by default. Some tables whose keys, TTLs or skip indexes depend on tuple subcolumns extracted from Dynamic, Variant, JSON or Nullable(Tuple) columns need allow_nullable_tuple_in_extracted_subcolumns = 0 in the default profile before first startup. Read the full entry if you use these types.
• CPU target (26.6). The default x86 build now targets x86-64-v3, which requires AVX2. Hosts without AVX2 need the amd64compat build.

Defaults that change results or behaviour

These changes do not stop the server, but they can change query results, part counts or client behaviour without an error. Most can be reverted per setting, and several entries name the compatibility setting as a way to restore earlier defaults.

Version	Change	How to restore
26.5	date_time_input_format and cast_string_to_date_time_mode default to best_effort, so strings that used to fail may now parse	Set both to basic
26.8	max_insert_threads defaults to auto, which can change the number of parts and the order of inserted rows	Set it to 1, or compatibility below 26.8
26.8	The X-ClickHouse-Format HTTP header now overrides the query’s FORMAT clause	Review clients that send the header
26.8	Unquoted JSON numbers for DateTime and DateTime64 are read as Unix timestamps	Check ingestion pipelines that send raw scaled values
26.8	arrayIntersect and arraySymmetricDifference no longer count repeated values within one argument as several	Re-test queries that rely on the old result
26.9	The analyzer can no longer be disabled; enable_analyzer = 0 is rejected and compatibility does not revert it	None; queries must work with the analyzer

The analyzer change matters most for older estates. The changelog notes it has been the default since 24.3, but teams that kept it off for specific queries must fix those queries before moving to 26.9. The changelog suggests using a version older than 26.9 to compare behaviour with the old query analysis.

Storage and replication changes

Two changes affect how data is written and how mixed-version clusters behave during a rolling upgrade.

Default compression (26.9). The default compression method moves from LZ4 to ZSTD(3) for client and server network traffic. For MergeTree column data the built-in default becomes size-aware: LZ4 for parts below 100 MB and ZSTD(3) at or above it. The changelog describes the change as backward compatible, because compressed frames are self-describing, and expects better compression ratios at a modest increase in CPU use. To keep the old behaviour, set network_compression_method = 'LZ4' or use compatibility for network traffic, and set CODEC(LZ4) or the server compression default for column data. Measure CPU headroom on your own workload before and after.

Lightweight update patch parts (26.8). Patch parts for lightweight UPDATE use a new v2 on-disk format. During a rolling upgrade from a version before 26.8, keep patch_parts_version = 'v1', or use compatibility, until every replica is upgraded.

The upgrade guide also notes that checksum mismatch errors can appear while replicas run different versions, and should stop once all replicas match. Plan to finish a rolling upgrade promptly rather than leave a cluster mixed.

Security hardening that needs grants or configuration

Several 2026 changes close paths where user SQL could act with the server’s own rights. They are improvements, but each can break an existing job until grants or configuration are updated.

• S3 credentials (26.7). S3 access from user SQL no longer resolves the server’s own cloud credentials, such as instance profiles or environment credentials, by default. Such requests need explicit credentials or NOSIGN.
• PostgreSQL database engines (26.8). PostgreSQL and MaterializedPostgreSQL databases now respect remote_url_allow_hosts when created or attached.
• TLS file paths from SQL (26.8). MySQL source certificates can no longer be given as file paths from SQL; use the new ssl_ca_pem, ssl_cert_pem and ssl_key_pem parameters.
• Implicit include file (26.8). include_from no longer defaults to /etc/metrika.xml. Add it explicitly to each config file that relied on it.
• Backups to disks (26.9). BACKUP and RESTORE with Disk(...) now require WRITE ON DISK or READ ON DISK grants. Check the identity your backup job uses.
• File renaming (26.9). rename_files_after_processing now requires WRITE ON FILE as well as READ ON FILE.

Other removals to search for include the library dictionary source and the Apache Arrow library-based reader (26.8), the config-based workload scheduling sections (26.7), and the read_resource and write_resource disk options (26.9).

An upgrade procedure for 26.3 LTS to 26.8 LTS or 26.9

1. Choose the target line. 26.8 LTS suits teams that prefer fewer, larger upgrades. 26.9 brings the analyzer and compression changes now, so the next LTS will not.
2. Read every changelog section between your current and target versions, as the upgrade guide recommends, and list each change that applies to your estate.
3. Inventory metadata on a production copy: window views, CatBoost usage and grants, WebAssembly UDF settings, insert_deduplication_version, tables using tuple subcolumns in keys, and the proxy tables the 26.9 entries identify with SELECT database, name FROM system.tables WHERE engine = 'Proxy'.
4. Check hardware for AVX2, and confirm the package or image you will deploy.
5. Keep custom configuration in config.d, as the upgrade guide advises, because config.xml can be overwritten during an upgrade.
6. Restore a recent backup into a staging cluster on the target version. Run representative queries, ingestion jobs and backup jobs, and compare results with production.
7. Decide which old defaults to pin with explicit settings or compatibility, and record why and for how long.
8. Run the rolling upgrade one replica per shard at a time, as the upgrade guide describes, watching Keeper and server logs. Upgrade Keeper separately, after the servers.
9. Remember that downgrade works only if new features have not been used. Avoid adopting new features until the upgrade is accepted.

Our ClickHouse OSS page and migration and modernization services describe how we run this kind of change in practice.

When a managed route is worth considering

This year’s changes show the cost of operating ClickHouse yourself: someone must read each changelog, test each upgrade and track the security-update list. For many teams that work is worthwhile, because it keeps full control of versions, hardware and data location. Others prefer to hand version management to a provider. ClickHouse Cloud, available through Bassirah’s ClickHouse partner route, is a separate commercial offering with its own upgrade policy and terms, not the same product as the open-source server.

How Bassirah can help

We help teams on self-managed ClickHouse inventory their exposure to these changes, rehearse the upgrade on a staging copy and run the rolling upgrade with a tested rollback plan. Our open-source support is independent engineering, not vendor support: upstream fixes follow the ClickHouse community’s timeline, as described in our support model.