{"id":13671467,"url":"https://github.com/n0vad3v/simple-multinode-clickhouse-cluster","last_synced_at":"2025-04-12T03:32:38.430Z","repository":{"id":108426565,"uuid":"458042932","full_name":"n0vad3v/simple-multinode-clickhouse-cluster","owner":"n0vad3v","description":"Deploy a simple Multi-Node Clickhouse Cluster with docker-compose in minutes.","archived":false,"fork":false,"pushed_at":"2022-02-11T04:57:51.000Z","size":143,"stargazers_count":17,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T23:08:53.611Z","etag":null,"topics":["clickhouse","clickhouse-cluster","clickhouse-pool","clickhouse-server","docker-compose"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n0vad3v.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-11T04:17:00.000Z","updated_at":"2024-10-24T15:37:54.000Z","dependencies_parsed_at":"2023-03-13T14:26:08.529Z","dependency_job_id":null,"html_url":"https://github.com/n0vad3v/simple-multinode-clickhouse-cluster","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n0vad3v%2Fsimple-multinode-clickhouse-cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n0vad3v%2Fsimple-multinode-clickhouse-cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n0vad3v%2Fsimple-multinode-clickhouse-cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n0vad3v%2Fsimple-multinode-clickhouse-cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n0vad3v","download_url":"https://codeload.github.com/n0vad3v/simple-multinode-clickhouse-cluster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248512745,"owners_count":21116674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","clickhouse-cluster","clickhouse-pool","clickhouse-server","docker-compose"],"created_at":"2024-08-02T09:01:10.366Z","updated_at":"2025-04-12T03:32:38.407Z","avatar_url":"https://github.com/n0vad3v.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Simple Multi Node Clickhouse Cluster\n\n![](./topo.png)\n\nI hate those single-node clickhouse clusters and manually installation, I mean, why should we:\n\n* Running multiple clickhouse instance inside one docker-compose. (e.g: [tetafro/clickhouse-cluster](https://github.com/tetafro/clickhouse-cluster))\n* Manually install JRE, download zookeeper.tar.gz, and modifying those annoying config files like a hell as some Chinese blog/book does (e,g: [ClickHouse集群多实例部署](https://blog.csdn.net/ashic/article/details/105901792), [2021年最新 大数据 Clickhouse零基础教程](https://www.bilibili.com/video/BV1yf4y1M7gw?p=8))\n\nthis is just weird!\n\nSo this repo tries to solve these problem.\n\n## Note\n\n* This is a simplified model of Multi Node Clickhouse Cluster, which lacks: LoadBalancer config/Automated Failover/MultiShard Config generation.\n* All clickhouse data is persisted under `event-data`, if you need to move clickhouse to some other directory, you'll just need to move the directory(that contains `docker-compose.yml`) and `docker-compose up -d` to fire it up again.\n* `Host` network mode is used to simplify the whole deploy procedure, so you might need to create addition firewall rules if you are running this on a public accessible machine. \n\n## Prerequisites\n\nTo use this, we need `docker` and `docker-compose` installed, recommended OS is `ubuntu`, and it's recommended to install `clickhouse-client` on machine, so on a typical ubuntu server, doing the following should be sufficient.\n\n```bash\napt update\ncurl -fsSL https://get.docker.com -o get-docker.sh \u0026\u0026 sh get-docker.sh \u0026\u0026 rm -f get-docker.sh\napt install docker-compose clickhouse-client -y\n```\n\n## Usage\n\n1. Clone this repo\n2. Edit the necessary server info in `topo.yml`\n3. Run `python3 generate.py`\n4. Your cluster info should be in the `cluster` directory now\n5. Sync those files to related nodes and run `docker-compose up -d` on them\n6. Your cluster is ready to go\n\n\nIf you still cannot understand what I'm saying above, see the example below.\n\n## Example Usage\n\n### Edit information\n\nI've Clone the repo and would like to set a 3-master clickhouse cluster and has the following specs\n\n* 3 replica(one replica on each node)\n* 1 Shard only\n\n![](./demo-cluster.png)\n\nSo I need to edit the `topo.yml` as follows:\n\n```yml\nglobal:\n clickhouse_image: \"yandex/clickhouse-server:21.3.2.5\"\n zookeeper_image: \"bitnami/zookeeper:3.6.1\"\n\nzookeeper_servers:\n - host: 192.168.33.101\n - host: 192.168.33.102\n - host: 192.168.33.103\n\nclickhouse_servers:\n - host: 192.168.33.101\n - host: 192.168.33.102\n - host: 192.168.33.103\n\nclickhouse_topology:\n - clusters:\n - name: \"novakwok_cluster\"\n shards:\n - name: \"novakwok_shard\"\n servers:\n - host: 192.168.33.101\n - host: 192.168.33.102\n - host: 192.168.33.103\n```\n\n### Generate Config\n\nAfter `python3 generate.py`, a structure has been generated under `cluster` directory, looks like this:\n\n```\n➜ simple-multinode-clickhouse-cluster git:(master) ✗ python3 generate.py \nWrite clickhouse-config.xml to cluster/192.168.33.101/clickhouse-config.xml\nWrite clickhouse-config.xml to cluster/192.168.33.102/clickhouse-config.xml\nWrite clickhouse-config.xml to cluster/192.168.33.103/clickhouse-config.xml\n\n➜ simple-multinode-clickhouse-cluster git:(master) ✗ tree cluster \ncluster\n├── 192.168.33.101\n│   ├── clickhouse-config.xml\n│   ├── clickhouse-user-config.xml\n│   └── docker-compose.yml\n├── 192.168.33.102\n│   ├── clickhouse-config.xml\n│   ├── clickhouse-user-config.xml\n│   └── docker-compose.yml\n└── 192.168.33.103\n ├── clickhouse-config.xml\n ├── clickhouse-user-config.xml\n └── docker-compose.yml\n\n3 directories, 9 files\n```\n\n### Sync Config\n\nNow we need to sync those files to related hosts(of course you can use ansible here):\n\n```\nrsync -aP ./cluster/192.168.33.101/ root@192.168.33.101:/root/ch/\nrsync -aP ./cluster/192.168.33.102/ root@192.168.33.102:/root/ch/\nrsync -aP ./cluster/192.168.33.103/ root@192.168.33.103:/root/ch/\n```\n\n### Start Cluster\n\nNow run `docker-compose up -d` on every hosts' `/root/ch/` directory.\n\n### Validation\n\nOn 192.168.33.101, use `clickhouse-client` to connect to local instance and check if cluster is there.\n\n```\nroot@192-168-33-101:~/ch# clickhouse-client \nClickHouse client version 18.16.1.\nConnecting to localhost:9000.\nConnected to ClickHouse server version 21.3.2 revision 54447.\n\n192-168-33-101 :) SELECT * FROM system.clusters;\n\nSELECT *\nFROM system.clusters \n\n┌─cluster──────────────────────────────────────┬─shard_num─┬─shard_weight─┬─replica_num─┬─host_name──────┬─host_address───┬─port─┬─is_local─┬─user────┬─default_database─┬─errors_count─┬─estimated_recovery_time─┐\n│ novakwok_cluster │ 1 │ 1 │ 1 │ 192.168.33.101 │ 192.168.33.101 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ novakwok_cluster │ 1 │ 1 │ 2 │ 192.168.33.102 │ 192.168.33.102 │ 9000 │ 0 │ default │ │ 0 │ 0 │\n│ novakwok_cluster │ 1 │ 1 │ 3 │ 192.168.33.103 │ 192.168.33.103 │ 9000 │ 0 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards │ 1 │ 1 │ 1 │ 127.0.0.1 │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards │ 2 │ 1 │ 1 │ 127.0.0.2 │ 127.0.0.2 │ 9000 │ 0 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards_internal_replication │ 1 │ 1 │ 1 │ 127.0.0.1 │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards_internal_replication │ 2 │ 1 │ 1 │ 127.0.0.2 │ 127.0.0.2 │ 9000 │ 0 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards_localhost │ 1 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_cluster_two_shards_localhost │ 2 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_shard_localhost │ 1 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_shard_localhost_secure │ 1 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 9440 │ 0 │ default │ │ 0 │ 0 │\n│ test_unavailable_shard │ 1 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 9000 │ 1 │ default │ │ 0 │ 0 │\n│ test_unavailable_shard │ 2 │ 1 │ 1 │ localhost │ 127.0.0.1 │ 1 │ 0 │ default │ │ 0 │ 0 │\n└──────────────────────────────────────────────┴───────────┴──────────────┴─────────────┴────────────────┴────────────────┴──────┴──────────┴─────────┴──────────────────┴──────────────┴─────────────────────────┘\n↘ Progress: 13.00 rows, 1.58 KB (4.39 thousand rows/s., 532.47 KB/s.) \n13 rows in set. Elapsed: 0.003 sec. \n```\n\nLet's create a DB with replica:\n\n```\n192-168-33-101 :) create database novakwok_test on cluster novakwok_cluster;\n\nCREATE DATABASE novakwok_test ON CLUSTER novakwok_cluster\n\n┌─host───────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐\n│ 192.168.33.103 │ 9000 │ 0 │ │ 2 │ 0 │\n│ 192.168.33.101 │ 9000 │ 0 │ │ 1 │ 0 │\n│ 192.168.33.102 │ 9000 │ 0 │ │ 0 │ 0 │\n└────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘\n← Progress: 3.00 rows, 174.00 B (16.07 rows/s., 931.99 B/s.) 99%\n3 rows in set. Elapsed: 0.187 sec. \n\n192-168-33-101 :) show databases;\n\nSHOW DATABASES\n\n┌─name──────────┐\n│ default │\n│ novakwok_test │\n│ system │\n└───────────────┘\n↑ Progress: 3.00 rows, 479.00 B (855.61 rows/s., 136.61 KB/s.) \n3 rows in set. Elapsed: 0.004 sec. \n\n```\n\nConnect to another host to see if it's really working.\n\n```\nroot@192-168-33-101:~/ch# clickhouse-client -h 192.168.33.102\nClickHouse client version 18.16.1.\nConnecting to 192.168.33.102:9000.\nConnected to ClickHouse server version 21.3.2 revision 54447.\n\n192-168-33-102 :) show databases;\n\nSHOW DATABASES\n\n┌─name──────────┐\n│ default │\n│ novakwok_test │\n│ system │\n└───────────────┘\n↘ Progress: 3.00 rows, 479.00 B (623.17 rows/s., 99.50 KB/s.) \n3 rows in set. Elapsed: 0.005 sec. \n\n```\n\n## License\n\nGPL","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn0vad3v%2Fsimple-multinode-clickhouse-cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn0vad3v%2Fsimple-multinode-clickhouse-cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn0vad3v%2Fsimple-multinode-clickhouse-cluster/lists"}