Planning inputs
Topology is a JSON file in etcd that lists shard groups, hash indexes and key ranges. The example uses xxhash on id with four ranges. Schema comes from the authoritative shard and refreshes periodically, not per query.
Neki makes a sharded Postgres cluster look like one server to the application. The example has customers and orders tables on four shards. Both tables are hashed by their own id, so a customer's orders sit on other shards.
The client connects to a router, which completes TLS and SCRAM authentication and reports ReadyForQuery. The router accepts simple and extended protocol messages and parses the SQL into an AST. It checks for a cached plan, then plans using cached schema and topology.
The plan has one route node per table and a join in the router. Route nodes send Parse, Bind, Execute and Sync messages inside protobuf requests to a sidecar next to each Postgres. The sidecar runs the query on a pooled connection and streams rows back, and the router joins and returns them.
Topology is a JSON file in etcd that lists shard groups, hash indexes and key ranges. The example uses xxhash on id with four ranges. Schema comes from the authoritative shard and refreshes periodically, not per query.
A nested loop would run a scatter query for every customer. A hash join loads customers into a router hash table, then scatters one orders query. The planner builds from customers because 100,000 rows need less memory than about 300,000 orders. If the table exceeds its memory budget, both inputs partition by join key and join one partition at a time.
Each Postgres connection is a backend process that uses memory even when idle. The sidecar lets many routers share warm connections. It resets session settings and checks the role before each use, which prevents role poisoning.
For AVG across shards, the router asks for SUM and COUNT per shard, combines them and divides. Averaging shard averages gives wrong answers.
| No. | Chose | Instead of | Why |
|---|---|---|---|
| D1 | Hash join in the router | Nested loop join | The nested loop needs thousands of shard queries, while the hash join needs 8. |
| D2 | Sidecar with pooled gRPC streams | Direct router connections to Postgres | Direct connections waste Postgres memory and do not share well across many routers. |
| D3 | Copy encoded values without decoding | This saves CPU on the return path. |
| Scatter route | A query sent to every shard because it has no shard key filter. |
|---|---|
| Sidecar | A helper process that runs next to each Postgres instance. |
| SCRAM-SHA-256 | A password login method that never sends the password. |
| Portal | Postgres state that tracks one running bound statement. |