High availability
Neki uses Postgres physical replication to copy write-ahead log (WAL) records from each shard’s primary to its replicas. If a primary becomes unavailable, Neki can promote an eligible replica and update the shard topology to use the new primary. A failover can briefly interrupt queries or connections while the shard changes primaries. Applications should retry transient connection and query failures. If a replica needs a WAL segment that no source can supply, Neki fences that replica from normal use. Once the shard primary is reachable, Neki restores the replica from the last backup and the admin joins it to the primary so replication can resume. This repairs the replica without changing the shard primary. Replication durability and read visibility are separate. WAL can be durable on a replica before that replica has replayed the change. A successful write therefore does not guarantee that an immediate replica read will return that change. Send reads that require the latest committed data to the primary.Send reads to replicas
Neki sends reads to shard primaries by default. To use replicas, select Route queries to a replica on the Connect page or set the Neki target when the connection starts. Forpsql, use PGOPTIONS:
How Neki chooses a replica
For each shard, the router starts with replicas that are serving and have known replication lag. It then orders the candidates using recency, locality, and session affinity.
The default maximum reported lag is 15 minutes. A replica above that limit, or
one whose lag is unknown, is not eligible for reads. A replica between the
preferred and maximum thresholds is used only when no preferred replica is
available.
The
__neki.replica_recency, __neki.replica_locality, and
__neki.replica_affinity settings can make these preferences stricter, disable
them, or keep a session on the same preferred replica. See Choosing where
reads run for the supported
values.
When a query reaches more than one shard, Neki chooses a replica separately for
each shard. Cross-shard transactions do not provide atomic commit across all
shards, so the combined result can reflect slightly different points in time.
Replication lag and read consistency
Replication lag measures how far a replica is behind its primary. Zero seconds means the replica has replayed everything it has received from the primary. A higher value means recent changes may not be visible there yet. Replica reads work well for dashboards, analytics, exports, and other read-heavy workloads that can tolerate some delay. Use a primary connection for read-after-write paths or any query that must return the newest committed data. Replica reads do not guarantee read-your-writes or monotonic reads. A later read can move to another eligible replica and see older data than an earlier read. Session affinity reduces how often a connection moves between replicas, but it does not provide either guarantee. Neki can choose another replica when the preferred one is unavailable, no longer meets the routing policy, or fails before serving a query.Monitor replicas
The database dashboard shows replication lag on each replica card. A value of0s means that replica is caught up. Each replica also has a chart shortcut
that opens the Shards tab of the Metrics page with that node selected.
If a replica has high or unknown lag, Neki can exclude it from read traffic.
Check the node’s replication lag, health, CPU, memory, and IOPS on Shards,
then compare its disk, storage, and WAL activity on Storage.