pg-status 2.0.0

This is a major release. It changes the units of one configuration
variable and adds new fields to JSON responses — operators upgrading
from 1.6.x should review the Breaking changes section before
deploying.

Breaking changes

pg_status__sleep renamed to pg_status__sleep_ms

The poll interval is now configured in milliseconds instead of
seconds. The old variable name is no longer supported.

Update any config that sets pg_status__sleep.

/status and /hosts response shape changed

Both endpoints now return lag_ms and lag_bytes for each host. For
dead hosts (alive: false) these are null and sync_by_time /
sync_by_bytes are false. Clients that pin to the old key set must
be updated to tolerate the additional fields.

Old /status body:

{ "master": false, "alive": true, "sync_by_time": true, "sync_by_bytes": true }

New /status body:

{ "master": false, "alive": true, "lag_ms": 0, "sync_by_time": true, "lag_bytes": 0, "sync_by_bytes": true, "lsn": "0/3000060" }

New features

Per-request lag thresholds

The replica-selection endpoints accept optional lag_ms and
lag_bytes GET parameters, overriding the global thresholds for that
single request.

• /replica — a missing parameter means no constraint on that
  dimension. Pass ?lag_ms=X and/or ?lag_bytes=Y to constrain.
• /sync_by_time, /sync_by_bytes, /sync_by_time_or_bytes,
  /sync_by_time_and_bytes — a missing parameter falls back to the
  global pg_status__sync_max_lag_ms / pg_status__sync_max_lag_bytes.

This lets a single pg-status instance serve clients with different
freshness requirements (e.g. a read-after-write path that needs
lag_ms ≤ 50 and a reporting path that's happy with anything alive).

Lag fields in /status and /hosts

lag_ms and lag_bytes are reported per host so clients can
implement their own selection logic on top of pg-status's raw data.

GET /most_sync_by_bytes

Returns the host of the most byte-synchronous replica — the one with the smallest lag_bytes among replicas that still satisfy the time threshold. Unlike the /sync_by_* endpoints, this endpoint does not use round-robin: selection is deterministic (ties are broken by host order).
Per-request lag_bytes query parameter overrides the global threshold for this request only.
If no replica satisfies threshold, the master’s host is returned.

LSN query parameter (read-your-writes)

The /replica, /sync_by_*, and /most_sync_by_bytes endpoints also
accept an optional min_lsn query parameter — a strict freshness
filter that guarantees the chosen host has replayed at least up to a
given WAL position. This is the primitive for read-your-writes
consistency: instead of relying on lag_ms / lag_bytes heuristics,
the caller supplies an exact LSN and pg-status only returns a replica
that has caught up to it.

The value must be a PostgreSQL LSN in canonical HEX/HEX form (for
example, 0/3000060). An invalid format produces HTTP 400 with
{"error_text": "Invalid min_lsn"}. A missing parameter means no LSN
constraint and stacks with the lag parameters described above.

If no replica has replayed to min_lsn, the master is returned as a
fallback.

Read-your-writes pattern. After a write to the master, capture
pg_current_wal_lsn() and pass it to the next read request:

INSERT INTO ...;
SELECT pg_current_wal_lsn();   -- returns e.g. "0/3000060"

# follow-up read is guaranteed to see the write:
GET /replica?min_lsn=0/3000060

Either a replica that has already replayed at least to 0/3000060 is
returned, or the master is returned.