- Choose a fixed number of buckets (for example,
1000buckets, numbered0–999). - Hash each user ID into one of those buckets using a deterministic hash.
- Maintain a small bucket-to-shard map that assigns each bucket to one shard.
- Compute the bucket from the user ID:
bucket = hash(user_id) % 1000. - Look up the shard for that bucket in the bucket map, then route the request to that shard.
371 and Leo to bucket 120. Their bucket assignments never change because the number of buckets and the modulo operation remain fixed. What can change is the bucket-to-shard mapping.

- A user always stays in the same bucket; only the bucket-to-shard mapping can change.
- Because the number of buckets is fixed, this strategy is commonly called the fixed-buckets approach.
- If you have 4 shards and
1000buckets, each shard initially owns roughly1000 / 4 = 250buckets. - Adding a 5th shard means redistributing buckets so each shard owns about
1000 / 5 = 200buckets. Each existing shard hands off about50buckets to the new shard, so only ~200 out of 1000 buckets move (≈20% of the buckets), rather than moving every user.
Practical routing example
Moving a bucket (safe migration)
Suppose we need to move bucket
602 from shard 2 to a new shard. Rather than moving users individually, we move the whole bucket. To keep the system available and consistent, use this four-step procedure:
- Copy: In the background, copy all existing rows for bucket
602fromshard 2to the new shard. Shard2continues to serve traffic for the bucket while this bulk copy runs.

-
Catch up (replicate incremental changes): While the bulk copy is running, stream or replay new writes for bucket
602fromshard 2to the new shard so the new copy can catch up with ongoing updates. -
Cutover (brief pause): Pause writes for bucket
602for a very short window (often a second or a few seconds), apply any final changes to the new shard so both copies are identical, and atomically update the bucket map to point bucket602at the new shard. After this update, reads and writes for bucket602are routed to the new shard. -
Remove old copy: After traffic is confirmed to be routed to the new shard and the new shard is healthy, remove the old copy on
shard 2.

Fixed buckets make resharding predictable and low-cost: users remain in the same bucket indefinitely, and resharding only updates the bucket-to-shard map. Pick a large bucket count (for example, thousands of buckets) so you can reassign small groups of users (fine-grained buckets), balance load precisely, and keep per-bucket traffic low during cutover.
- Choose the bucket count large enough to allow fine-grained rebalancing, but not so large that the bucket map becomes unwieldy. Thousands of buckets is a common starting point.
- Ensure the copy and catch-up pipeline is robust: use change-data-capture (CDC), write-ahead-log replication, or a similar mechanism to stream incremental updates reliably.
- Keep the cutover window as small as possible; plan for retries and client backoff during the short write pause.
- Monitor bucket-level traffic and hot buckets. Very hot buckets can still require special handling (sharding within a bucket or application-level throttling).
- Consistent hashing (Wikipedia)
- Designing Distributed Systems: Sharding strategies and trade-offs
- Change Data Capture patterns