> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grow the Cluster
> How to add a Citus worker node, inspect and rebalance shards for even distribution, and run cross-shard joins
This final lesson shows how to add a new worker node to a Citus cluster, verify the node and shard distribution, rebalance shards onto the new machine, and run queries that join tables across shards.
## 1) Add the new worker node from the coordinator
Run the following on the coordinator (control plane) with psql to add `worker3` to the cluster:
```bash theme={null}
controlplane ~ on ☁️ (us-east-1) ➜ psql -h localhost -p 5432 -U postgres -d chirp -c "SELECT citus_add_node('worker3', 5432);"
```
The coordinator returns the new node id:
```text theme={null}
citus_add_node
----------------
4
```
This confirms the cluster now knows about the new worker.
## 2) Inspect shard distribution for the `users` table
Query the `citus_shards` catalog on the coordinator to see how many shards for the `users` table exist on each worker:
```bash theme={null}
controlplane ~ on ☁️ (us-east-1) ➜ psql -h localhost -p 5432 -U postgres -d chirp -c "SELECT nodename, count(*) AS shards FROM citus_shards WHERE table_name = 'users'::regclass GROUP BY nodename ORDER BY nodename;"
```
The raw output from the coordinator shows the current shard counts:
```text theme={null}
nodename | shards
---------+--------
worker1 | 3
worker2 | 3
worker3 | 2
```
Summary of shard distribution:
| Worker node | Shard count |
| - | - |
| `worker1` | 3 |
| `worker2` | 3 |
| `worker3` | 2 |
As shown, `worker3` was added and already hosts some shards, but the distribution is not yet balanced across all workers.
To even out shard placement across the cluster, run a rebalance operation (for example, `rebalance_table_shards`) so shards move onto the new node(s). After the rebalance completes, re-run the shard-count query above to confirm an even distribution.
## 3) Rebalance shards onto the new node
A typical rebalance step for a table named `users` is:
```sql theme={null}
-- Run this on the coordinator
SELECT rebalance_table_shards('users');
```
Rebalancing will redistribute shards among workers to achieve a more even shard count and storage usage. Depending on cluster size and data volume, rebalance can take time and consume I/O/CPU on workers.
Running a rebalance on a production cluster may increase load and affect query latency. Schedule rebalances during maintenance windows or throttle them if your Citus deployment supports that.
## 4) Verify shard distribution again
After rebalance completes, run the same `citus_shards` query from step 2 to verify shards are distributed evenly:
```bash theme={null}
controlplane ~ on ☁️ (us-east-1) ➜ psql -h localhost -p 5432 -U postgres -d chirp -c "SELECT nodename, count(*) AS shards FROM citus_shards WHERE table_name = 'users'::regclass GROUP BY nodename ORDER BY nodename;"
```
Confirm the output matches your expected balance (for example, equal or near-equal shard counts across `worker1`, `worker2`, and `worker3`).
## 5) Running cross-shard joins
After adding nodes and rebalancing, you can run queries that join tables which live on different shards. The coordinator will plan and dispatch the distributed query across workers. Example:
```sql theme={null}
-- Example cross-shard join run on the coordinator
SELECT u.id, u.username, p.post_text
FROM users u
JOIN posts p ON u.id = p.user_id
WHERE u.id = 123;
```
Citus will route parts of this query to the appropriate workers holding the relevant shards and aggregate the results on the coordinator.
## Links and references
* [Citus rebalancing and shard management documentation](https://docs.citusdata.com/en/stable/administration/cluster_management.html#rebalancing-shards)
* [Citus reference: citus\_add\_node](https://docs.citusdata.com/en/stable/api_reference.html)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.