Skip to main content
In this example, you’ll learn how to set up a simple ClickHouse cluster which both replicates and scales. It consisting of two shards and two replicas with a 3-node ClickHouse Keeper cluster for managing coordination and keeping quorum in the cluster.
The architecture of the cluster you will be setting up is shown below:
Although it is possible to run ClickHouse Server and ClickHouse Keeper combined on the same server, we strongly recommend using dedicated hosts for ClickHouse keeper in production environments, which is the approach we will demonstrate in this example.Keeper servers can be smaller, and 4GB RAM is generally enough for each Keeper server until your ClickHouse Servers grow large.

​
Prerequisites

1

​
Set up directory structure and test environment

Example filesThe following steps will walk you through setting up the cluster from scratch. If you prefer to skip these steps and jump straight to running the cluster, you can obtain the example files from the examples repository ‘docker-compose-recipes’ directory.
In this tutorial, you will use Docker compose to set up the ClickHouse cluster. This setup could be modified to work for separate local machines, virtual machines or cloud instances as well.Run the following commands to set up the directory structure for this example:
Add the following docker-compose.yml file to the clickhouse-cluster directory:
docker-compose.yml
Create the following sub-directories and files:
  • The config.d directory contains ClickHouse server configuration file config.xml, in which custom configuration for each ClickHouse node is defined. This configuration gets combined with the default config.xml ClickHouse configuration file that comes with every ClickHouse installation.
  • The users.d directory contains user configuration file users.xml, in which custom configuration for users is defined. This configuration gets combined with the default ClickHouse users.xml configuration file that comes with every ClickHouse installation.
Custom configuration directoriesIt is a best practice to make use of the config.d and users.d directories when writing your own configuration, rather than directly modifying the default configuration in /etc/clickhouse-server/config.xml and etc/clickhouse-server/users.xml.The line
Ensures that the configuration sections defined in the config.d and users.d directories override the default configuration sections defined in the default config.xml and users.xml files.
2

​
Configure ClickHouse nodes

​
Server setup

Now modify each empty configuration file config.xml located at fs/volumes/clickhouse-{}/etc/clickhouse-server/config.d. The lines which are highlighted below need to be changed to be specific to each node:
Each section of the above configuration file is explained in more detail below.

​
Networking and logging

External communication to the network interface is enabled by activating the listen host setting. This ensures that the ClickHouse server host is reachable by other hosts:
The port for the HTTP API is set to 8123:
The TCP port for interaction by ClickHouse’s native protocol between clickhouse-client and other native ClickHouse tools, and clickhouse-server and other clickhouse-servers is set to 9000:
Logging configuration is defined in the <logger> block. This example configuration gives you a debug log that will roll over at 1000M three times:
For more information on logging configuration, see the comments included in the default ClickHouse configuration file.

​
Cluster configuration

Configuration for the cluster is set up in the <remote_servers> block. Here the cluster name cluster_2S_2R is defined.The <cluster_2S_2R></cluster_2S_2R> block defines the layout of the cluster, using the <shard></shard> and <replica></replica> settings, and acts as a template for distributed DDL queries, which are queries that execute across the cluster using the ON CLUSTER clause. By default, distributed DDL queries are allowed, but can also be turned off with setting allow_distributed_ddl_queries.internal_replication is set to true so that data is written to just one of the replicas.
The <cluster_2S_2R></cluster_2S_2R> section defines the layout of the cluster, and acts as a template for distributed DDL queries, which are queries that execute across the cluster using the ON CLUSTER clause.

​
Keeper configuration

The <ZooKeeper> section tells ClickHouse where ClickHouse Keeper (or ZooKeeper) is running. As we’re using a ClickHouse Keeper cluster, each <node> of the cluster needs to be specified, along with its hostname and port number using the <host> and <port> tags respectively.Set up of ClickHouse Keeper is explained in the next step of the tutorial.
Although it is possible to run ClickHouse Keeper on the same server as ClickHouse Server, in production environments we strongly recommend that ClickHouse Keeper runs on dedicated hosts.

​
Macros configuration

Additionally, the <macros> section is used to define parameter substitutions for replicated tables. These are listed in system.macros and allow using substitutions like {shard} and {replica} in queries.

​
User configuration

Now modify each empty configuration file users.xml located at fs/volumes/clickhouse-{}/etc/clickhouse-server/users.d with the following:
/users.d/users.xml
In this example, the default user is configured without a password for simplicity. In practice, this is discouraged.
In this example, each users.xml file is identical for all nodes in the cluster.
3

​
Configure ClickHouse Keeper

Next you will configure ClickHouse Keeper, which is used for coordination.

​
Keeper setup

In order for replication to work, a ClickHouse keeper cluster needs to be set up and configured. ClickHouse Keeper provides the coordination system for data replication, acting as a stand in replacement for Zookeeper, which could also be used. ClickHouse Keeper is, however, recommended, as it provides better guarantees and reliability and uses fewer resources than ZooKeeper. For high availability and to keep quorum, it is recommended to run at least three ClickHouse Keeper nodes.
ClickHouse Keeper can run on any node of the cluster alongside ClickHouse, although it is recommended to have it run on a dedicated node which allows scaling and managing the ClickHouse Keeper cluster independently of the database cluster.
Create the keeper_config.xml files for each ClickHouse Keeper node using the following command from the root of the example folder:
Modify the empty configuration files which were created in each node directory fs/volumes/clickhouse-keeper-{}/etc/clickhouse-keeper. The highlighted lines below need to be changed to be specific to each node:
/clickhouse-keeper/keeper_config.xml
Each configuration file will contain the following unique configuration (shown below). The server_id used should be unique for that particular ClickHouse Keeper node in the cluster and match the server <id> defined in the <raft_configuration> section. tcp_port is the port used by clients of ClickHouse Keeper.
The following section is used to configure the servers that participate in the quorum for the raft consensus algorithm:
ClickHouse Cloud simplifies managementClickHouse Cloud removes the operational burden associated with managing shards and replicas. The platform automatically handles high availability, replication, and scaling decisions. Compute and storage are separate and scale based on demand without requiring manual configuration or ongoing maintenance.Read more
4

​
Test the setup

Make sure that docker is running on your machine. Start the cluster using the docker-compose up command from the root of the cluster_2S_2R directory:
You should see docker begin to pull the ClickHouse and Keeper images, and then start the containers:
To verify that the cluster is running, connect to any one of the nodes and run the following query. The command to connect to the first node is shown:
If successful, you will see the ClickHouse client prompt:
Run the following query to check what cluster topologies are defined for which hosts:
Query
Response
Run the following query to check the status of the ClickHouse Keeper cluster:
Query
Response
The mntr command is also commonly used to verify that ClickHouse Keeper is running and to get state information about the relationship of the three Keeper nodes. In the configuration used in this example, there are three nodes working together. The nodes will elect a leader, and the remaining nodes will be followers.The mntr command gives information related to performance, and whether a particular node is a follower or a leader.
You may need to install netcat in order to send the mntr command to Keeper. Please see the nmap.org page for download information.
Run the command below from a shell on clickhouse-keeper-01, clickhouse-keeper-02, and clickhouse-keeper-03 to check the status of each Keeper node. The command for clickhouse-keeper-01 is shown below:
The response below shows an example response from a follower node:
Response
The response below shows an example response from a leader node:
Response
With this, you have successfully set up a ClickHouse cluster with two shards and two replicas. In the next step, you will create a table in the cluster.
5

​
Create a database

Now that you have verified the cluster is correctly setup and is running, you will be recreating the same table as the one used in the UK property prices example dataset tutorial. It consists of around 30 million rows of prices paid for real-estate property in England and Wales since 1995.Connect to the client of each host by running each of the following commands from separate terminal tabs or windows:
You can run the query below from clickhouse-client of each host to confirm that there are no databases created yet, apart from the default ones:
Query
Response
From the clickhouse-01 client run the following distributed DDL query using the ON CLUSTER clause to create a new database called uk:
You can again run the same query as before from the client of each host to confirm that the database has been created across the cluster despite running the query only from clickhouse-01:
6

​
Create a table on the cluster

Now that the database has been created, next you will create a table with replication.Run the following query from any of the host clients:
Notice that it is identical to the query used in the original CREATE statement of the UK property prices example dataset tutorial, except for the ON CLUSTER clause and use of the ReplicatedMergeTree engine.The ON CLUSTER clause is designed for distributed execution of DDL (Data Definition Language) queries such as CREATE, DROP, ALTER, and RENAME, ensuring that these schema changes are applied across all nodes in a cluster.The ReplicatedMergeTree engine works just as the ordinary MergeTree table engine, but it will also replicate the data. It requires two parameters to be specified:
  • zoo_path: The Keeper/ZooKeeper path to the table’s metadata.
  • replica_name: The table’s replica name.

The zoo_path parameter can be set to anything you choose, although it is recommended to follow the convention of using prefix
where:
  • {database} and {table} will be replaced automatically.
  • {shard} and {replica} are macros which were defined previously in the config.xml file of each ClickHouse node.
You can run the query below from each host’s client to confirm that the table has been created across the cluster:
Query
Response
7

​
Insert data into a distributed table

To insert data into the table, ON CLUSTER can’t be used as it does not apply to DML (Data Manipulation Language) queries such as INSERT, UPDATE, and DELETE. To insert data, it is necessary to make use of the Distributed table engine. As you learned in the guide for setting up a cluster with 2 shards and 1 replica, distributed tables are tables which have access to shards located on different hosts and are defined using the Distributed table engine. The distributed table acts as the interface across all the shards in the cluster.From any of the host clients, run the following query to create a distributed table using the existing replicated table we created in the previous step:
On each host you will now see the following tables in the uk database:
Data can be inserted into the uk_price_paid_distributed table from any of the host clients using the following query:
Run the following query to confirm that the data inserted has been evenly distributed across the nodes of our cluster:

​
Conclusion

The advantage of this cluster topology with 2 shards and 2 replicas is that it provides both scalability and fault tolerance. Data is distributed across separate hosts, reducing storage and I/O requirements per node, while queries are processed in parallel across both shards for improved performance and memory efficiency. Critically, the cluster can tolerate the loss of one node and continue serving queries without interruption, as each shard has a backup replica available on another node. The main disadvantage of this cluster topology is the increased storage overhead—it requires twice the storage capacity compared to a setup without replicas, as each shard is duplicated. Additionally, while the cluster can survive a single node failure, losing two nodes simultaneously may render the cluster inoperable, depending on which nodes fail and how shards are distributed. This topology strikes a balance between availability and cost, making it suitable for production environments where some level of fault tolerance is required without the expense of higher replication factors. To learn how ClickHouse Cloud processes queries, offering both scalability and fault-tolerance, see the section “Parallel Replicas”.
Last modified on June 23, 2026