Grow the Cluster

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:

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:

 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:

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:

 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:

-- 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:

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:

-- 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.

Why One Database Isn't Enough

Sharding Fundamentals

Routing and Hot Shards

Shard Keys and Partitioning

Resharding and Cross-Shard Queries

1) Add the new worker node from the coordinator

2) Inspect shard distribution for the `users` table

3) Rebalance shards onto the new node

4) Verify shard distribution again

5) Running cross-shard joins

Links and references

Watch Video

Practice Lab

​1) Add the new worker node from the coordinator

​2) Inspect shard distribution for the users table

​3) Rebalance shards onto the new node

​4) Verify shard distribution again

​5) Running cross-shard joins

​Links and references

Watch Video

Practice Lab

1) Add the new worker node from the coordinator

2) Inspect shard distribution for the `users` table

3) Rebalance shards onto the new node

4) Verify shard distribution again

5) Running cross-shard joins

Links and references