PlanetScaleHarshit Gangal8 min readintermediate
The architecture of Neki
Summary
Neki is PlanetScale’s sharding layer for vanilla PostgreSQL that presents a single Postgres endpoint while routing queries across a fleet of Postgres instances. It does this with a set of tightly‑coupled components—Router, Sidecar, PostgresManager, Admin, Operator, and etcd‑backed Data Topology—each handling a specific piece of the scaling, failover, and query‑planning puzzle.
- Neki runs unmodified PostgreSQL instances; all scaling and sharding logic lives in external components.
- PostgresManager starts/stops the postgres process and configures replication for each instance.
- Sidecar pools connections to PostgreSQL backends, offering three connection‑lifetime tiers (autocommit, transaction, advisory‑lock) based on Router hints.
- A shard = a primary + ≥2 replicas; one shard is designated the authoritative shard to keep custom type OIDs consistent across the cluster.
Understanding Neki’s architecture shows how to build a production‑grade, sharded Postgres service without forking the database engine. The design demonstrates practical patterns—sidecar connection pooling, OID authority, Kubernetes operators, and distributed query planning—that can be reused in oth…
8/10
