PlanetScale — The architecture of Neki (2026-09-18)

Harshit Gangal, planetscale engineering blog, 18 September 2026. Arrived by Telegram. It closes a hole this wiki had written down twice: vitess says Neki is "PlanetScale's Postgres equivalent, which this wiki has only as a name," and database-sharding and planetscale-768-servers both name it without describing it. Now described — see neki.

T1, by the rule that tiers a first-party page on what its claims rest on. This is a component walkthrough: what each process is, where it runs, what it talks to. Architecture is the artifact's own fact and PlanetScale is its primary source. The post makes no benchmark and no performance claim — there is no number in it to discount — which is what keeps the tier clean rather than generous.

The status is the one thing a reader must not lose: Platform Preview, not general availability.

The claim under the architecture

"Neki is built as a sharding and scaling solution for real Postgres. It's not a fork, nor a wire-compatible reimplementation, nor a MySQL sharding idea wearing a Postgres label." Ordinary PostgreSQL instances store rows in Postgres data pages under MVCC, run transactions, and answer psql. Everything Neki adds is built around them.

That third clause is aimed at its own sibling. vitess is the MySQL system by the same company, and the post is pre-empting the reading that Neki is Vitess with the labels changed. The component inventory supports it in one direction and undercuts it in another — see neki for the seven parts and the Vitess correspondence, which is closer than the disclaimer suggests.

The detail this wiki did not have from anywhere

OIDs force a global singleton. Postgres identifies objects by numeric OID, not by name; a client reads a column's type OID off the wire to interpret the bytes and may cache it. Independent shards assign a custom type different OIDs, so one shard in the cluster is designated authoritative and translates OIDs in every other shard's responses to match. That shard's Sidecar also watches for schema changes and pushes them to the Routers.

This is the kind of constraint that only shows up when you shard a specific engine rather than "a database," and this wiki had no example of one. It is a Postgres-only problem: MySQL has no equivalent wire-level object identity to reconcile, which is a concrete reason Neki could not be Vitess retargeted even if PlanetScale had wanted it to be.

Three connection lifetimes, and the Router has to say which. Postgres forks a backend per connection and caps how many exist, so the Sidecar pools. But the pool cannot treat every checkout the same: a multi-statement transaction holds its connection until commit or rollback; a session-scoped advisory lock needs a connection of its own, because the lock outlives whatever transaction is open and cannot share; everything else returns the connection the moment the statement finishes. The Sidecar knows which because the Router tells it — autocommit, open transaction, or pinned session.

Failover uses pg_rewind. When Admin promotes a replica, it brings diverged instances onto the new primary's timeline by copying only what changed since divergence, rather than re-cloning.

Three durability policies, enforced by Postgres itself. Async (no wait), sync (wait for one replica), cross-zone sync (wait for a replica in another AZ). Postgres's own synchronous replication does the enforcing; Admin's job is keeping the configuration correct as replicas join, leave, or a failover moves the primary to a different zone. See write-ahead-logging and postgres-wal-reliability for what the wait is actually waiting on.

Cross-shard joins are pushed down when they can be. If both sides of a join sit on one shard, the Router ships the join there. When they don't, the Router runs it, choosing between nested-loop, hash and merge joins on cost estimates — a query engine, not a proxy. Compare cross-shard-queries.

Buffering is one mechanism used twice. A query that failed against an unavailable primary and is safe to retry gets held, for a bounded time and queue size, then released gradually once a healthy primary exists. The same mechanism covers the cutover at the end of a Reshard, MoveTables or OnlineDDL. Rarely the limit is hit first and the client sees the error.

What the post does not say

• No numbers. No latency, no throughput, no shard count, no comparison with Vitess or with anything else. Good for the tier, and it means this wiki still cannot say whether Neki works, only what it is.
• No consistency model for cross-shard transactions. The durability policies cover replication within a shard. Whether a transaction touching two shards is atomic, and by what mechanism, is not addressed. See consistency-models; this is the question the page most wants answered.
• No failure story. Architecture described, never an incident.

Related

neki · planetscale · vitess · database-sharding · cross-shard-queries · postgresql · harshit-gangal · planetscale-768-servers · synthesis