Moving ClickHouse to a new cluster or new hardware

Moving ClickHouse to a new cluster or new hardware: the short answer on effort

The method for moving self-managed ClickHouse to new hardware or a new cluster layout depends on three things: the size of the data, the version gap between the source and target servers, and how much downtime your clients can tolerate. The copy itself is rarely the hard part. Most of the effort goes into planning the target topology, verifying that the restored data matches the source, and running a controlled cutover of clients, which means the work is mostly planning, verification and cutover rather than moving bytes. Ask your team to write down the table count, total compressed size, peak write rate and the longest outage the business accepts before choosing between replica addition, BACKUP and RESTORE, or a remote copy over remoteSecure.

ClickHouse Server is licensed under the Apache License 2.0, so you can run the move entirely with your own engineers, in your own data centers or cloud accounts, without a vendor license decision. That also means no vendor will plan the cutover for you unless you hire one. The move involves provisioning the new nodes, installing a matching ClickHouse version, configuring ClickHouse Keeper for any replicated tables, recreating users, roles and settings profiles, and then transferring data. Whether you do this in-house or with a partner, the scope should be agreed in writing before work starts, covering who runs each rehearsal, who signs off the verification results and who owns rollback if the cutover fails. Confirm the exact version of the target release against the ClickHouse docs on self-managed upgrades before you order hardware, because the compatibility window determines whether old and new servers can run side by side during the transition.

Which ClickHouse objects move cleanly and which need work

This table maps each ClickHouse object type to how it behaves when a self-managed cluster moves to new hardware or a new cluster. Read it as a checklist: objects in the first group copy with their data, while the rows marked for rework need explicit recreation or configuration on the target before cutover.

Object	Moves with data copy	What to do on the target
MergeTree tables	Yes	Confirm table definitions, ordering keys and partitioning match on the target before loading data. Compare with SHOW CREATE TABLE output.
ReplicatedMergeTree tables	Not applicable	Keeper paths are tied to the cluster. Recreate tables with the target's ZooKeeper or Keeper path and replica macros, then restore or sync data into them.
Distributed tables	Not applicable	Distributed tables point at cluster names defined in config. Recreate them after the target cluster definition exists, or they will route to nothing or to the wrong nodes.
Users, roles and grants	Not applicable	Access control stored with SQL-driven workflows may be restored with the backup of access entities, but verify grants, passwords and authentication methods on the target.
Row policies and settings profiles	Not applicable	Confirm each row policy and profile applies to the same users and roles after restore. Test a sample query under each role before cutover.
Quotas	Not applicable	Quota limits and intervals must be re-checked on the target. Usage counters reset, so plan how limits are interpreted during the first days.
External authenticators (LDAP, Kerberos, SSL, JWT, HTTP)	Not applicable	Authenticator configuration lives in server config, not in data. Copy and adapt it, then confirm each directory, realm or certificate chain is reachable from the new hosts.
Cluster definitions and Keeper ensemble	No	Cluster XML, remote server lists, shard and replica layout and Keeper node addresses are written per environment. Rebuild them for the new hardware and verify with system.clusters.
Storage policies and disks	No	Disk paths, object storage endpoints and storage policies are configuration, not data. Define them on the target and confirm each table's policy name matches.
Default user permissions	No	The default user starts with full permissions. Create named administrative users, then restrict or disable the default user on the target as a deliberate step.

Documented methods for moving data between ClickHouse clusters

ClickHouse documents three main ways to move data between self-managed clusters: replica addition, backup and restore, and direct copy over remote table functions. Each one fits a different combination of data volume, network path and tolerance for downtime, so the choice should be made before the new hardware is racked.

Adding replicas on new hardware

Add new servers as replicas of existing ReplicatedMergeTree tables, coordinated through ClickHouse Keeper, so the new nodes fetch missing parts from a healthy replica. A recovered replica syncs on its own, which makes this the lowest-effort path when old and new hosts can reach the same Keeper ensemble and the same versions. Check Keeper connectivity, the replica count per shard, and that the new hosts run a version the existing nodes can replicate with. Confirm the exact DDL against your release before starting.

Backup and restore to local disk

Use BACKUP and RESTORE to write full or incremental backups of databases, tables or partitions to a local disk on the source side, then restore them on the new cluster. This suits moves where the two clusters cannot reach each other directly, or where the team wants a portable artifact to test with. Plan disk space for the backup set and for the restore target, and confirm that backup and restore use the same ClickHouse version family on both ends.

Backup to S3-compatible or Azure storage

Write backups to S3-compatible object storage or Azure Blob Storage, then restore from the same location on the new cluster. Object storage decouples the two clusters in time and place, which helps when the move spans sites or runs in phases with incremental backups. Check bucket permissions, endpoint reachability, egress costs in your own cloud account, and whether the new environment can read the storage path without exposing credentials to the wider network.

Direct copy with remoteSecure

Copy rows directly from the source cluster into the target with INSERT ... SELECT statements that read through remote table functions over remoteSecure, which encrypts the connection between servers. This fits moderate data sizes where both clusters are reachable on the network and the team wants to control the copy window table by table. Confirm the exact remote function syntax and TLS settings for your version, and set user and network rules on both sides so the copy does not widen access.

Matching the method to data size

The right method depends less on a fixed size threshold than on how long the copy takes against the change window and whether writes continue during the move. Replica addition keeps data current with the source, backups give a point-in-time snapshot, and direct copy needs a catch-up pass for rows written during the copy. Measure a representative table in a pre-production environment, then extrapolate the total copy time and bandwidth before choosing. Ask the team running the migration to write down the cutover window for each table.

Verifying copies and confirming syntax

Whichever method you use, compare row counts, partition lists and checksums of key tables between source and target before any client is pointed at the new cluster. ClickHouse documents that a backup never test-restored will probably not restore properly, so run at least one restore onto a spare cluster as a rehearsal. Confirm all DDL, function names and settings against the documentation for the exact version you run, since syntax can change between releases.

Sequence for a parallel run and client cutover

This sequence moves a self-managed ClickHouse workload to a new cluster or new hardware while the source keeps serving clients, so the cutover happens only after the copy is verified and a restore has been proven. It ends with a source cluster kept for a retention period as a fallback.

Inventory databases, tables, users and Keeper topology
The platform owner lists every database, table, materialized view, dictionary, user, role, row policy, settings profile and quota on the source, along with the replica and shard layout and the Keeper ensemble. Record the exact ClickHouse version on each node, because mixed versions in one cluster must fall inside the compatibility window. Access control objects are easy to miss, so export them alongside the data definitions. The step is done when the inventory is reviewed by the data owners and every table has a named owner and a known size.
Check versions against the supported list
Compare the source and target server versions with the versions listed as supported in the ClickHouse security policy and with the upgrade guide's compatibility window, which covers two LTS versions. If the target is a newer release, read the changelog for backward-incompatible changes before any data moves. Confirm with your own environment team which version your operating system, Keeper and client libraries support. The step is done when a written version decision exists and the change notes that affect your schemas have an owner.
Build the target and run a pilot restore
Install the target cluster on the new hardware, configure Keeper on dedicated hosts, and take a backup of one representative database from the source to the storage the target can read. Restore it into a spare cluster, not the production target, then compare schema and sample queries. The backup documentation warns that a backup never test-restored will probably not restore properly when needed, so this restore is a required gate, not an optional rehearsal. The step is done when the restore completes, the schema matches, and the test is recorded with its outcome and the commands used.
Load the full dataset into the target
Choose the initial load method by data size and network path. A full BACKUP to S3-compatible or Azure Blob storage followed by RESTORE on the target is usually the path for large datasets, while adding a replica on the new hardware suits a cluster where the new nodes can join and sync directly. Run the load during a low write period and keep the source writable. The step is done when the target reports all tables present and the load job logs show no unresolved errors.
Run a catch-up period with writes continuing
Keep the source receiving production writes while the target catches up. For backup-based loads, take an incremental backup of changes since the full backup and restore it on the target, repeating until the lag is acceptable to the data owners. For replica-based loads, confirm the new replicas show a small replication queue and no stalled tasks. Track which upstream producers, such as Kafka topics or ingestion jobs, must be paused or redirected at cutover. The step is done when the agreed lag is reached and the upstream producer plan is signed off.
Verify row counts and checksums per table
For each table, compare row counts between source and target at a fixed point in time, then compare checksums over agreed columns or partitions. Include materialized views, dictionaries and access control objects in the comparison list. Investigate any mismatch before proceeding, since the ingestion and merge state can differ while writes are still arriving. The step is done when every table in the inventory has a recorded comparison result and the data owners have accepted each one in writing.
Cut over clients to the new connection targets
Briefly stop or redirect writers, apply the final incremental catch-up, and then switch client connection settings, DNS names, load balancers or application configuration to the target. Update TLS certificates, users and any remoteSecure settings used by other clusters at the same time. Keep the source in read-only or unreachable-for-writes mode so no write lands in two places. The step is done when a test write and read succeed from each client group and the monitoring dashboards show traffic on the target only.
Decommission the source after a retention period
Keep the source cluster and its backups for a retention period agreed with the data owners and the compliance team, so a rollback remains possible. Confirm the retention period in writing before the cutover, since it sets how long duplicate hardware and storage costs continue. When the period ends and no rollback is needed, remove access, revoke credentials, delete data according to the retention policy and record the disposal. The step is done when the disposal record is filed and the source no longer appears in the inventory.

Choosing a method by data size, version gap and downtime tolerance

Replica addition joins new hardware into the existing cluster as additional replicas of the same shards. It suits moves where the cluster identity, Keeper ensemble and table definitions stay the same and the hardware changes underneath. ClickHouse replicates data with ReplicatedMergeTree tables coordinated by ClickHouse Keeper, and according to the replication guide, a recovered replica automatically syncs missing data from a healthy replica without manual intervention. Catch-up writes are therefore handled by the replication queue, not by a separate copy step.

Network prerequisites: New nodes need reliable, low-latency paths to Keeper and to their peer replicas on the replication ports.
Storage prerequisites: Each new node needs disk capacity for its share of every replicated table, plus headroom for merges during the sync.
Catch-up behavior: Writes continue on existing replicas while the new replica fetches parts, so the team should watch the replication queue and replica lag until it drains.
Version constraint: The new nodes must run a server version the existing cluster can work with inside the compatibility window.
Removal path: Retiring the old hardware is a second step that drops replicas only after the new ones are verified.

Confirm with your own environment whether the Keeper nodes and the network paths meet the replication guide's expectations before adding any replica.

Remote copy moves data between clusters with INSERT ... SELECT through the remoteSecure table function over TLS. It fits smaller datasets or a targeted set of tables, where a full backup cycle would add more work than the data justifies, or where only some tables are moving. Because the copy runs through normal query paths, it can also be used to reshape data while moving it, although that adds risk and verification effort.

Network prerequisites: The source cluster must be reachable from the destination on the secure native port, with TLS certificates and a user that has read access to the source tables.
Security prerequisites: Use a dedicated account with minimal grants on the source, and confirm how credentials are stored in the job that runs the copy.
Catch-up writes: Copy in passes, first a bulk load of historical partitions, then repeated copies of recent partitions, and stop writes for the final pass.
Verification: Compare counts and aggregates per partition between source and destination before cutover.
Scale limit: Long-running copies over a busy network extend the window in which source and destination diverge, so this method suits bounded datasets.

Confirm with your own environment whether the network path, certificates and account permissions allow the copy without opening the cluster more broadly than the migration requires.

Keeping source and target versions inside the compatibility window

Version choice decides whether a cluster move is a copy or a project. ClickHouse aims to keep a one-year compatibility window covering two LTS versions, during which two server versions can work together in one cluster. Before you pick a target, confirm that your source and the target sit inside that window, because a source running an older line may need an intermediate upgrade first. Treat the window as a goal stated by the vendor, and confirm the current boundaries against the self-managed upgrade guide and your own release plan.

Start with the ClickHouse security policy, which lists versions 26.9, 26.8, 26.7 and 26.3 as currently supported with security updates and marks all other versions as unsupported. A source outside that list should be treated as a security exposure that the move must not carry forward. Next, read the changelog for every release between your current version and the target. The production FAQ notes that minor backward-incompatible changes can occur, so record each one that touches settings, data types, functions or replication behavior, and decide which of them affect your queries and ingestion jobs.

Then stage the target version before any production data moves. Build a pre-production cluster on the target version and load it with a representative copy of your largest tables, including the partition layout and the TTL rules you use in production. Replay a sample of real dashboard and ingestion queries, compare results and timings with the source, and confirm that Keeper and replication behave as expected on the new hardware. Ask your team or partner to name who signs off on the staged results and which queries count as the acceptance set.

What usually goes wrong during a ClickHouse cluster move

Most failed cluster moves are not caused by the ClickHouse engine itself. They come from assumptions carried across the move: that replicas protect data, that a backup works, that the new Keeper ensemble matches the old one, and that clients will reconnect unchanged. Each card below names one of these failure points and the check that prevents it.

Replication mistaken for backup

Replicas copy every write, including a bad DROP or a corrupted part, so a healthy replica does not give you a point to return to. During a move, teams often assume the new cluster's replicas are the recovery plan. Keep a separate BACKUP to storage outside both clusters, and confirm that the backup set covers every database and table you plan to move, not only the ones that are easy to list.

Backups never test-restored

A backup that has never been restored is an unverified assumption. The ClickHouse backup documentation warns that such a backup will probably not restore properly when needed. Before cutover, restore the backup to a spare cluster built on the new hardware, run row counts and checksums against the source for representative tables, and record the restore time so the rollback plan is based on measured numbers.

Keeper misconfigured on new hosts

ReplicatedMergeTree depends on ClickHouse Keeper, and a new ensemble with wrong server IDs, missing peers or shared hosts can split replicas or leave tables read-only. The replication guide recommends at least three Keeper nodes on dedicated hosts in production. Check quorum, confirm each replica registers under the expected path, and verify that a recovered replica syncs from its peer before any client is pointed at the cluster.

Versions outside the compatibility window

Mixing server versions beyond the supported pairing can break replication, DDL or query behavior during a staged move. Before copying data, compare the source version with the target and read the changelog for any minor backward-incompatible changes. Confirm both versions sit within the window in the upgrade guide, and confirm the target version appears in the security policy as supported.

Lost writes during cutover

Data written to the old cluster after the final copy but before clients switch will be missing on the new one. This gap is easy to miss because both clusters report healthy. Define a write freeze or a dual-write window, stop or redirect ingestion producers in a known order, and reconcile row counts per partition for the last hours of data before retiring the old endpoint.

Access control and TLS gaps

A new cluster can start with the default user, which has all permissions, or lose users, roles, row policies and quotas that were created by hand on the old one. Certificates and authentication settings also differ between hosts, so clients that worked before fail on the new endpoint. Export access control objects, restrict the default user, and test each client's TLS and authentication path against the new endpoint before cutover.

What drives the cost and duration of the move

This table lists the factors that change the effort and cost of moving a self-managed ClickHouse workload, and marks which ones are paid once and which recur. Use it to turn a rough plan into a written scope that a partner or your own team can price and schedule.

Driver	Why it changes cost or effort	What to ask for in the scope and quote
Total data volume and table count	Volume sets copy time and network load for BACKUP and RESTORE or replica addition. Table count drives the number of checks and object definitions to move.	Data size per database and table, row counts, and an estimate of copy time per method, measured on a sample
Shards and replicas	Each shard and replica adds copy streams, Keeper coordination and validation work. Replica addition is simpler per node but depends on the new topology matching the old one.	Target topology diagram, shard and replica counts on both sides, and the Keeper plan
Version gap and LTS jump	Two server versions can work together in one cluster during a move only within the compatibility window. Larger gaps mean more changes to queries, settings and table definitions to test.	Current and target versions, the upgrade path chosen, and a list of breaking changes reviewed against your queries
Network path between sites	Cross-site copies depend on bandwidth, latency, TLS overhead and firewall rules. Slow or restricted paths extend copy windows and retries.	Bandwidth and latency between sites, firewall changes required, and the remoteSecure endpoints to be opened
Client applications and connection strings	Each application, dashboard, ETL job and service account needs a new host, port or certificate and a tested cutover. Hidden clients are the most common cause of late changes.	Inventory of every client, owner, connection string, and the cutover order for each
Access control complexity	Users, roles, row policies, settings profiles and quotas must be exported, recreated and checked. Heavy row policy use increases verification work.	Count of users, roles and row policies, and whether external authenticators such as LDAP or JWT must be reconfigured
Parallel running period	Keeping old and new clusters in sync or both available extends operations, duplicated infrastructure and data sync effort until rollback is no longer needed.	Length of the parallel period, who monitors both sides, and the rollback trigger and deadline
Restore test schedule (recurring)	The backup documentation warns that a backup never test-restored will probably not restore properly, so restore tests on a spare cluster recur after the move as well as before cutover.	Number of restore rehearsals before cutover, frequency afterwards, and who owns and records each test
Pre-production validation	Representative data and queries must be run on the target version before production traffic moves, as the production FAQ recommends. Results comparison is a one-time cost per workload.	Test dataset definition, query set, result comparison method and acceptance criteria written before work starts

Questions buyers ask before moving ClickHouse to new hardware

How much does moving ClickHouse to a new cluster cost?

No single figure applies, because the cost follows from the written scope: the data volume, the number of shards and replicas, the migration method, and how many client applications need cutover work. Engineering effort is the main component, covering planning, network and TLS setup between old and new clusters, the data copy, verification, and the cutover window. Hardware or cloud capacity for the new cluster is a separate cost you pay your provider directly, and it is often the larger one. Ask for a quote that lists each phase, the environments it touches (staging and production), the restore test, and what happens if the cutover slips. Recurring costs such as Keeper nodes and monitoring continue after the move and belong in the ownership estimate.

How long does a ClickHouse cluster move take?

Duration depends mostly on data size, network throughput between the two sites, the number of tables that need custom handling, and how much time the team can spend on a staging rehearsal. Methods that copy data over remoteSecure are bounded by bandwidth, while BACKUP and RESTORE to shared object storage add a write and read step that also needs time. Client cutover adds time when many applications connect directly to hosts. Ask for a timeline that separates the rehearsal, the bulk copy, the catch-up of recent inserts, and the cutover window. Any figure you receive should trace back to measured throughput in your environment rather than a generic rule.

Can our internal team move ClickHouse without a partner?

Yes, many teams do this in-house, provided they have someone who understands ReplicatedMergeTree, ClickHouse Keeper, and the chosen backup or copy method. The work is less about the commands and more about proving the result: row counts, checksums on key tables, query parity, and a timed restore. Internal teams often underestimate the cutover, which touches DNS, connection strings, service accounts, and any job that writes to the old cluster during the switch. A fixed-scope engagement can cover the parts your team does not have time or practice for, while your staff keep ownership of the production environment. Decide based on who will run the cluster afterward.

What does the move need from our staff and environment?

Plan for network paths between the old and new clusters, TLS certificates that both sides trust, and firewall rules for the native and HTTP ports that the chosen method uses. You need named owners for the source and target hosts, a change window that business owners accept, and access to a staging environment with representative data and queries. Storage for backups must be reachable from both clusters if you use BACKUP and RESTORE, and it must have capacity for the full backup plus any incremental chain. Inventory every client, scheduled job, and dashboard that reads or writes the cluster so cutover does not miss one. Confirm each item with your own security and network teams.

Is replication enough as a backup for ClickHouse?

No. Replication keeps copies of data in sync across replicas, so a bad delete, a faulty query, or corruption can spread to every copy. The ClickHouse backup documentation makes this point directly and recommends BACKUP and RESTORE for full and incremental backups to local disk, S3-compatible storage, or Azure Blob Storage. Keep backups outside the failure domain of the cluster, and treat them as a separate system with their own access controls and retention. During a hardware move, the backup taken just before cutover is also your rollback point, so its age and integrity matter. Read the ClickHouse backup documentation before designing the schedule.

How do we handle the version gap between the old and new clusters?

Check the versions first, because the move is the moment when a version jump can be combined with new hardware. ClickHouse aims to keep a one-year compatibility window covering two LTS versions, in which two server versions can work together in one cluster, according to the self-managed upgrade guide. The security policy lists 26.9, 26.8, 26.7, and 26.3 as currently supported, and every other version is unsupported. If the source runs an older release, decide whether to upgrade it first in place or to move directly to a supported target, and test each option in staging. Read the changelog for backward-incompatible changes before choosing, and confirm the target version against the self-managed upgrade guide.

How do we confirm a restore actually works?

Restore a backup onto a spare cluster on a schedule, then compare results with the source. The ClickHouse backup documentation warns that a backup never test-restored will probably not restore properly when needed. Your check should cover row counts per table and partition, checksums or aggregates on business-critical columns, the presence of users, roles, row policies, and settings profiles, and a representative set of queries with expected results. Record the time the restore takes, because that number is the basis for your recovery planning. Repeat the test after every major change, including the hardware move itself, and keep the evidence for auditors and incident reviews.

How DeployOpen scopes and delivers a ClickHouse cluster move

DeployOpen plans, builds, tests and documents moves between self-managed ClickHouse clusters inside infrastructure you control. Each engagement starts from a written scope that fixes the method, the version path and the cutover plan before any data moves.

How we scope

Inventory source and target clusters, table sizes, replica layout and Keeper nodes before choosing a method.
Confirm source and target versions sit within the one-year compatibility window that covers two LTS versions.
Agree in writing the cutover window, client list, rollback point and who signs off each stage.

How we build

Build the target cluster with ReplicatedMergeTree tables, ClickHouse Keeper and matching settings to the source.
Move data with BACKUP and RESTORE or replica addition, using remoteSecure where data crosses networks.
Run a rehearsal on a spare cluster, comparing row counts and sample query results against the source.

How we hand over

Deliver a runbook with exact steps, checks, timings observed during rehearsal and rollback commands.
Document access control, users, roles and the restricted default user on the new cluster.
Hand over a restore test record showing that a backup taken after cutover was restored successfully.

How we support

Support post-cutover stabilization for the period set out in the written scope.
Offer ongoing upgrades, backup restore tests and monitoring reviews as a retainer.
Ask your team to confirm release channel, LTS choice and maintenance windows as part of the retainer scope.

Moving ClickHouse to a new cluster or new hardware