Introduction

Upgrading ClickHouse® is typically a straightforward process that brings new features, performance improvements, bug fixes, and better SQL compatibility. However, every major release can also introduce changes that affect operational workflows. One of the most important changes introduced in ClickHouse® 26.3 is related to its on-disk storage format.

Starting with ClickHouse® 26.3, once the server begins creating data using the new storage format introduced in this release, downgrading to an earlier ClickHouse® version is no longer supported. Older versions cannot understand the new data layout, and attempting to downgrade after new-format data parts have been written may result in startup failures, unreadable tables, or even data loss.

If your organization depends on rollback procedures as part of its upgrade strategy, this is a critical change to understand before deploying ClickHouse® 26.3 in production.

In this article, we'll explain why downgrades are no longer supported, how the new storage format works, the risks involved, and the best practices for safely upgrading production clusters.

Why Can't You Downgrade?

ClickHouse® stores data on disk using highly optimized internal storage formats. These formats evolve over time to support new capabilities, improve performance, reduce storage consumption, and enable new features.

ClickHouse® 26.3 introduces updates to some of these internal storage structures.

The upgrade process looks like this:

ClickHouse® 26.2
        │
        ▼
Upgrade to 26.3
        │
        ▼
New Data Parts Created
        │
        ▼
❌ Older Versions Cannot Read Them

Unlike SQL syntax or configuration files, the physical storage format is tightly coupled to the ClickHouse® engine itself. Once data has been written using a newer storage format, previous ClickHouse® binaries no longer understand those structures.

What Happens During an Upgrade?

Immediately after upgrading, your existing data remains in its original format.

However, ClickHouse® continuously performs background maintenance tasks.

These include:

• Background merges
• INSERT operations
• Mutations
• OPTIMIZE commands
• TTL merges

As these operations execute, new data parts begin using the updated storage format.

The process looks like this:

Upgrade
   │
   ▼
Old Data Parts
   │
Background Merge
   │
   ▼
New Format Data Parts

Initially, only a small portion of the data uses the new format. Over time, more and more data parts are rewritten until a significant portion of the database depends on the new storage structures.

At that point, reverting to an older ClickHouse® version becomes unsafe.

Why Introduce a New Storage Format?

Database storage engines continuously evolve.

New storage formats often provide:

• Faster query execution
• Better compression ratios
• Improved metadata handling
• Reduced storage overhead
• Support for new database features
• More efficient background processing

These improvements are one of the reasons ClickHouse® continues to deliver excellent analytical performance.

The downside is that older versions cannot always understand the new on-disk representation.

What Can Happen If You Downgrade?

Attempting to downgrade after new-format data parts have been created can cause several problems.

Possible outcomes include:

• ClickHouse® failing to start
• Tables becoming inaccessible
• Missing data parts
• Metadata inconsistencies
• Data corruption
• Permanent data loss

Even if the older server starts successfully, it may be unable to read tables containing newer storage structures.

Example Upgrade Timeline

Let's walk through a typical scenario.

Day 1

The server runs ClickHouse® 26.2.

26.2

├── Part A
├── Part B
└── Part C

Everything is stored using the older format.

Day 2

The administrator upgrades to ClickHouse® 26.3.

At this point, existing data is still readable because it has not yet been rewritten.

Day 3

Background merges execute automatically.

26.3

├── Part D (New Format)
├── Part E (New Format)
└── Part F (New Format)

The new storage format is now actively being used.

Day 4

The administrator decides to reinstall ClickHouse® 26.2.

Unfortunately:

• Part D cannot be read.
• Part E cannot be read.
• Part F cannot be read.

Result:

❌ Downgrade Failed

What Does This Mean for Production?

Organizations should treat upgrades to ClickHouse® 26.3 as one-way upgrades.

Instead of depending on binary downgrades, build your deployment process around careful validation and reliable backups.

A recommended production workflow is:

Backup
   │
   ▼
Upgrade Staging
   │
   ▼
Validate Applications
   │
   ▼
Upgrade Production
   │
   ▼
Monitor Cluster

This approach minimizes operational risk while providing a safe recovery path if problems occur.

Best Practices Before Upgrading

1. Create a Full Backup

Always create a verified backup before upgrading.

Possible backup methods include:

• ClickHouse® BACKUP command
• Filesystem snapshots
• Object storage backups
• Cloud provider snapshots

A reliable backup is the safest rollback strategy.

2. Test in a Staging Environment

Before touching production, upgrade a staging cluster.

Validate:

• SQL queries
• Dashboards
• Materialized Views
• Replication
• Scheduled jobs
• Applications
• Monitoring tools

Testing beforehand significantly reduces upgrade risk.

3. Read the Release Notes

Every major ClickHouse® release includes important information about:

• Breaking changes
• New features
• Configuration updates
• Compatibility notes

Never skip the release notes.

4. Schedule a Maintenance Window

Although rolling upgrades reduce downtime, production upgrades should still be scheduled during planned maintenance windows.

This allows enough time for validation and troubleshooting if necessary.

5. Monitor the Cluster After Upgrading

Once the upgrade is complete, monitor:

• Background merges
• Replication queues
• Query latency
• Disk usage
• CPU utilization
• Memory usage
• Server logs
• Application error rates

Early monitoring helps detect issues before users notice them.

What Is the Recommended Rollback Strategy?

Since binary downgrades are no longer reliable after new-format parts are created, the recommended recovery process is:

Problem Detected
        │
        ▼
Stop ClickHouse®
        │
        ▼
Restore Verified Backup
        │
        ▼
Install Previous Version
        │
        ▼
Start Server

Rather than attempting to reuse upgraded storage files, restore the database from a backup created before the upgrade.

This is the only reliable rollback strategy.

Upgrade Checklist

Before upgrading to ClickHouse® 26.3, verify the following:

Frequently Asked Questions

Can I downgrade immediately after upgrading?

Possibly—but only if ClickHouse® has not yet created any new-format data parts.

Once background merges, INSERT operations, mutations, or other maintenance tasks generate new-format parts, downgrading is no longer supported.

Does this affect replicated clusters?

Yes.

If one replica begins generating or exchanging new-format parts, replicas running older ClickHouse® versions will not be able to read them.

Upgrade planning becomes even more important in replicated environments.

Is this unique to ClickHouse®?

No.

Many database systems evolve their storage formats over time.

As new optimizations and capabilities are introduced, maintaining backward compatibility with much older storage engines eventually becomes impossible.

Key Takeaways

Common Upgrade Mistakes

Some of the most common mistakes include:

• Skipping backups because "the upgrade should be safe."
• Upgrading production before testing staging.
• Assuming rollback simply means reinstalling an older package.
• Ignoring release notes.
• Not monitoring background merges after upgrading.
• Forgetting that storage formats evolve alongside database engines.

Avoiding these mistakes greatly improves upgrade reliability.

Final Thoughts

ClickHouse® 26.3 delivers valuable improvements in performance, SQL compatibility, and overall database capabilities. Alongside those improvements comes an important operational consideration: once ClickHouse® begins writing data using the new storage format, downgrading to an earlier version is no longer supported.

Rather than viewing this as a limitation, it's an opportunity to adopt stronger upgrade practices. Reliable backups, staged testing, careful production rollouts, and post-upgrade monitoring provide a much safer recovery strategy than relying on binary downgrades.

If you're planning to upgrade to ClickHouse® 26.3, treat it as a one-way transition. Validate thoroughly before deployment, maintain verified backups, and monitor your environment closely after the upgrade. With the right preparation, you can take advantage of the latest features while minimizing operational risk and protecting your data.