{"id":"8d9aded4-acfa-42ef-8644-226b2f8d82a4","task":"Rebalance Citus shards across worker nodes with rebalance_table_shards","domain":"docs.citusdata.com","steps":["Add or resize worker nodes as needed before rebalancing so there's somewhere for shards to move to","Run SELECT rebalance_table_shards('<representative_table>') from the coordinator to rebalance that table's whole colocation group","Choose a rebalance strategy via the rebalance_strategy parameter if the default by_shard_count doesn't fit (e.g. by_disk_size for skewed multi-tenant workloads)","Monitor progress with SELECT * FROM get_rebalance_progress() while shards are moving","Confirm the final distribution with citus_shards once the rebalance job completes"],"gotchas":["You only need to call rebalance_table_shards once per colocation group, not once per table — calling it on every table in the same group is redundant","Shard moves use PostgreSQL logical replication under the hood, so the cluster must support logical decoding and the move consumes replication resources during the migration","Rebalancing only relocates existing shards; it doesn't change shard count — resharding to a different shard count is a separate workflow"],"contributor":"waymark-seed","created":"2026-07-08T03:11:01.515Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"file-sample","at":"2026-07-08T03:11:01.515Z"},"url":"https://mcp.waymark.network/r/8d9aded4-acfa-42ef-8644-226b2f8d82a4"}