Neki

planetscale's sharding system for PostgreSQL, and the Postgres counterpart to vitess. Named in this wiki since July 2026 and described only now, from PlanetScale's own component walkthrough (2026-09-18). Platform Preview at that date, not generally available.

It shards unmodified Postgres. Not a fork and not a wire-compatible reimplementation: real PostgreSQL instances hold the rows in Postgres data pages under MVCC, and every Neki component sits around them.

The seven parts

Component	Where it runs	What it does
Router	cluster edge	The single Postgres wire endpoint. Authenticates, parses, plans against the sharding layout, dispatches to Sidecars over gRPC, and executes cross-shard joins itself
Sidecar	beside each Postgres	Connection pool in three lifetimes; reports instance health and primary/replica role
PostgresManager	first process in the Postgres container	Owns the data directory; starts, stops and configures the `postgres` process, including replication setup for a joining instance
Replicator	beside each Postgres	Copies rows and decodes a [[logical-replication
Admin	control plane	Health-checks Sidecars, tracks replication lag, runs emergency failover and planned switchover (`pg_rewind`), keeps durability policy correct
Operator	Kubernetes	Owns pod lifecycle: builds a replacement and waits for it to catch up before deleting the old one, or rebuilds from scratch after a node loses ephemeral storage
etcd	control plane	The single authoritative copy of the Data Topology; components pick up changes with no restart

A shard is one Postgres cluster — a primary and its replicas, physically identical copies sharing a catalog. PlanetScale advises a primary plus two or more replicas, for availability and for read capacity.

The Postgres-specific problem: OID reconciliation

Postgres tracks objects by numeric OID, and a client reads a column's type OID off the wire to interpret the bytes, caching it for later. Two independent shards will assign a custom type different OIDs. So Neki designates one shard in the cluster as authoritative — the source of truth that translates OIDs in other shards' responses so they agree. That shard's Sidecar also watches for schema changes (a rename, a dropped column) and reports them to the Routers.

This is the sharpest thing on the page, because it is a constraint that could not be inherited from Vitess. MySQL has no equivalent wire-level object identity to reconcile. Sharding is often discussed as if the engine underneath were a detail; here the engine's own identifier scheme forces a cluster-wide singleton into the architecture.

Connection pooling in three lifetimes

Postgres forks a backend process per connection and caps the count, so the Sidecar pools — but not uniformly:

Shared — an autocommit statement checks a connection out and returns it when the statement ends.
Dedicated — a multi-statement transaction holds its connection until commit or rollback.
Reserved — a session-scoped advisory lock gets a connection to itself, because the lock has to outlive whatever transaction is open and cannot share.

The Sidecar does not infer which; the Router sends the classification with the query. The wiki's other pooler, pgbouncer, exposes the same three modes as a deployment-wide setting the operator picks once. Here it is per query, decided upstream — the same trade, moved.

Query planning, not just routing

The Router parses with a Postgres-compatible parser against the authoritative shard's catalog and plans against the current layout. Single-shard work is pushed down. A join whose sides sit on one shard goes to that shard whole. A join that genuinely spans shards is executed by the Router, which picks between nested-loop, hash and merge joins on cost estimates. That is a distributed query engine in the proxy, and it is the same shape as vitess's VTGate — see cross-shard-queries.

Durability, stated in three policies

Set per shard, enforced by Postgres's own synchronous replication rather than by Neki:

Async — the primary acknowledges without waiting for a replica.
Sync — waits for one replica; survives losing a node.
Cross-zone sync — waits for a replica in another availability zone; survives losing the primary's zone.

Admin's job is keeping that configuration true as replicas join or leave and as failover moves the primary between zones. postgres-wal-reliability covers what the acknowledgement actually means.

Reshaping a live database

Three workflows, all riding the Replicator's copy-then-follow-the-CDC-stream pattern:

MoveTables — relocate a set of tables, including importing from an external Postgres.
Reshard — redistribute across key ranges, splitting a shard that outgrew its capacity.
OnlineDDL — build a shadow table, keep it current through the same change-data-capture pipeline, then swap it in with a rename. Covers repartitioning and other changes that would otherwise block.

Each ends in a cutover, and the cutover reuses the Router's query buffering — the mechanism built for primary failover. One idea paying for itself twice.

How close is it to Vitess, really?

The post opens by denying that Neki is "a MySQL sharding idea wearing a Postgres label," and the component map argues both ways. Router↔VTGate and Sidecar↔VTTablet are the same division of labour, and the workflow names — MoveTables, Reshard, OnlineDDL — are Vitess's own, unchanged. The author is harshit-gangal, a top-five contributor to vitessio/vitess by commit count.

What is genuinely not transferable is everything the engine forced: OID reconciliation and the authoritative shard, pg_rewind on the failover path, logical-replication decoding as the data-movement primitive, and advisory locks as a third pooling tier. So the fair reading is neither the disclaimer nor its opposite: the topology and the operational vocabulary came from Vitess; the mechanisms came from Postgres.

What this wiki still cannot say

Whether it works. No latency, no throughput, no shard count, no comparison. The source carries no number at all.
What happens to a cross-shard transaction. The durability policies are per shard. Atomicity across shards — two-phase commit, or its absence — is not addressed anywhere in the source, and it is the question consistency-models would ask first.
How it behaves when something breaks. Architecture, never an incident.

the-architecture-of-neki · vitess · planetscale · database-sharding · cross-shard-queries · postgresql · pgbouncer · logical-replication · postgres-wal-reliability · consistency-models · postgres-kubernetes-operators