Logical Shard
also called Virtual Shard, Shard Slot
A unit of partitioned data that routing targets by name rather than by machine, so data can be moved between physical hosts without changing how anything is addressed.
The naive shard design routes with a hash modulo the number of databases. It works on the day it ships and makes the machine count part of the addressing scheme, so changing from 32 hosts to 96 rehashes most rows while the system is live.
A logical shard breaks that coupling. The key maps to a logical shard - one of a fixed, large number - and a separate mapping says which physical host currently holds it. Growing the estate means replicating a logical shard to a new host and cutting over, one shard at a time, with the routing key untouched.
Why it matters
Resharding is the most expensive operation a sharded system ever performs, and it is scheduled by growth rather than by choice. With logical shards it is a sequence of small, independently reversible moves. Without them it is a full data migration with a cutover, which is the kind of project that takes a quarter and is remembered.
The decision costs nothing on day one. Choosing 480 shards over 32 nodes instead of 32 databases is a configuration constant. It is one of the few architectural choices that is free to make and very expensive to retrofit.
Implementation patterns
- Pick a highly composite count. 480 divides evenly by 8, 12, 16, 24, 32, 48 and 60, so the physical topology can be almost any size without uneven shards. A prime count, or one equal to the machine count, is the trap.
- Keep the mapping in one authoritative place the routing layer reads, with a cache and a version so a stale router can be detected rather than silently wrong.
- Move with replication, then a short write freeze per shard. Replicate the logical shard to the target, catch up, freeze writes for that shard only, flip the mapping, unfreeze. The blast radius of a mistake is one shard.
- Embed the shard identifier in object identifiers where possible, as Pinterest described in 2015, so routing needs no lookup at all.
- Make schema migration shard-aware and resumable, because a change now runs hundreds of times.
Industry example
Notion sharded its Postgres estate into 480 logical shards in 2021, then in 2023 redistributed those shards onto a larger number of physical machines without changing the partition key or the application's routing logic. The 2021 choice of 480 is what made the 2023 operation a scheduling exercise. Notion also moved analytics off the transactional estate with change data capture, which is the necessary companion: once data is sharded by workspace, a query across all workspaces is exactly the query the design makes expensive.
Failure scenarios
- A shard count equal to the machine count, so the first capacity change rehashes the dataset.
- A stale routing map on one service, sending writes to the shard's old home after a move, which is data loss discovered later.
- Uneven logical shards because the key is skewed: one workspace or tenant far larger than the rest, so balancing logical shards does not balance load.
- Cross-shard queries creeping in through a new feature, turning every read into a fan-out with a tail latency equal to the slowest shard.
- Schema migrations timing out partway through a few hundred shards, leaving the estate in mixed states.
Trade-offs
| Choose | Gains | Pays |
|---|---|---|
| Many logical shards (hundreds) | Cheap rebalancing, topology is a scheduling decision | Hundreds of connections, migrations, vacuum schedules and metric series |
| Few shards equal to hosts | Simple to reason about, nothing extra to operate | Every capacity change is a data migration |
| No sharding, one large primary | No partition key in queries, transactions intact | A ceiling set by one machine's writes and working set |
When not to use it
Do not shard because read load is high - replicas solve that for a fraction of the cost, and sharding is close to irreversible because the partition key spreads into every query and job. Exhaust the cheaper sequence first: fix the query, add the index, add replicas, partition tables within one instance, move cold data out, use a bigger machine. Shard when write throughput or the active working set exceeds one machine.
And if the workload has no natural partition key, because queries routinely span whatever you would shard by, no shard count rescues it: the answer is a different data model or a database that distributes for you.
Interview question
Q: You are about to shard onto 32 database hosts. How many shards do you create, and what do you need in place before the first move so that going to 96 hosts in two years is a routine operation?
What a strong answer covers: far more logical shards than hosts, with a highly composite count · an authoritative, versioned shard-to-host map that routers read · replicate-catch-up-freeze-flip as the per-shard move, reversible at each step · shard-aware resumable migrations · the analytics escape hatch, because cross-shard queries are what the design makes expensive · and the prior question of whether sharding is warranted at all, given that replicas fix reads.
Quick check
Quiz: Why choose 480 logical shards for 32 machines? Because moving whole shards between hosts is cheap while rehashing rows is not, and 480 divides evenly across almost any future host count.
Flashcard: What makes resharding expensive? Baking the machine count into the routing function, so changing it moves most of the data.