PlanetScale architecture: how PlanetScale scaled (4 case studies)
We track 4 public engineering write-ups by PlanetScale, published between 2022 and 2026. Techniques that come up more than once: benchmarking (2) and horizontal sharding (2). Stack mentioned most: Neki (3) and PostgreSQL (3). 4 of the 4 state concrete scale numbers, for example "one primary and multiple replicas per shard". Each card below links to our short summary and the original post.
Designing a planned switchover for minimum disruption
When a Neki shard's primary has to step aside for a pod replacement, kernel upgrade or cell move, PlanetScale does a planned switchover instead of stopping Postgres the way Patroni does, so a failed switchover can quickly fall back to the old primary. Admin, Neki's control plane, first validates shard state, the target replica, logical failover slots and Postgres settings. Routers then proactively buffer primary-bound queries, the primary defaults new transactions to read-only, and the other replicas are disconnected to pin a final WAL position the target must replay. If the target can't catch up before a deadline, a config reload makes the old primary writable again. Buffered queries are replanned against the new primary, so apps see added latency instead of errors, and every acknowledged commit is on the target when it is promoted.
Shard design doesn't start from your tables
In Neki, PlanetScale's sharded Postgres, a shard group is the unit of co-location: tables in the same group that hash their shard key the same way (xxhash into a 64-bit keyspace split by key ranges) always land on the same shard. Sharding customers, orders, items and addresses by customer_id keeps single-customer queries and transactions on one shard, which matters because a transaction across two shards gets no atomic commit or shared snapshot. Lookup tables become reference tables copied to every shard, catalog tables get their own group keyed on lower(sku), range and modulo indexes support legacy schemes, and a global secondary index routes queries like orders by id without fanning out. Shard groups can be changed later with the Reshard workflow.
118 million queries per second on Neki
PlanetScale benchmarked Neki, its sharded Postgres, with single-shard primary-key point selects. Targeting about 200K QPS per shard, it went from 5 shards (about 1M QPS) to 50 (9.9M QPS, per-shard rate within 0.8%) to 512 shards and 480 routers, sustaining 118.5M QPS for 16 minutes over 1.22 PiB with a p99 of 6.06 ms at the router and about one error per 1.8 million queries. PlanetScale notes the run was read-only, primary-only with no replicas, and had no failover during the measured window.
One million queries per second with MySQL
PlanetScale benchmarked a horizontally sharded Vitess cluster up to one million QPS.