ClickHouse Cluster Management in Spring Boot Applications

December 13, 2025

#1

Managing a ClickHouse cluster in Spring Boot ensures scalability and reliability. Here’s how you can integrate and manage cluster queries.

1. Cluster Configuration in ClickHouse

Define a cluster in your ClickHouse config:

<yandex>
  <remote_servers>
    <my_cluster>
      <shard>
        <replica>
          <host>node1</host>
          <port>9000</port>
        </replica>
        <replica>
          <host>node2</host>
          <port>9000</port>
        </replica>
      </shard>
    </my_cluster>
  </remote_servers>
</yandex>

This defines shards and replicas.

2. Create Distributed Tables

CREATE TABLE users_local (
  id UInt32,
  name String,
  created_at DateTime
) ENGINE = MergeTree()
ORDER BY id;

CREATE TABLE users_dist AS users_local
ENGINE = Distributed('my_cluster', 'default', 'users_local', rand());

The distributed table queries the cluster.

3. Access from Spring Boot

List<Map<String, Object>> users = jdbcTemplate.queryForList(
  "SELECT * FROM users_dist LIMIT 20"
);

Spring Boot applications can query across all cluster nodes.

4. Handling Failover

With replication in your cluster, queries succeed even if one node is down. Spring Boot apps remain responsive.

5. Expose a Cluster API

@GetMapping("/api/users/cluster")
public List<Map<String,Object>> getClusterUsers() {
    return jdbcTemplate.queryForList("SELECT * FROM users_dist");
}

Clients can query data aggregated from multiple shards.