cd ..

$ cat ~/field-notes/read-replicas-replication-lag.md

Read Replicas: Why Your New Record Sometimes Disappears

A customer saves a new shipping address. The API reports success. The next page shows the old address. Refreshing a moment later fixes it.

The write may be perfectly durable. The read may simply have gone to a replica that had not replayed it yet.

Read replicas increase capacity for suitable reads. They also introduce a consistency boundary that the application has to recognize.

Commit and Replay Are Different Events

PostgreSQL streaming replication is asynchronous by default. A primary can acknowledge a transaction before a standby has applied it. PostgreSQL's standby documentation explains the replication modes.

For an application, the visible sequence can look like this:

primary: commit address version 8
API: return success
replica: still serving address version 7
replica: replay version 8

None of those steps requires a broken database. The mistake is promising a fresh view while routing the read somewhere allowed to lag.

Classify Reads by What They Promise

For the address editor, route the immediate follow-up read to the primary. Better still, return the saved representation in the write response so the interface can show the accepted result without another query.

An illustrative routing policy might be:

Read Candidate destination
public catalog browsing replica, if short staleness is acceptable
analytics summary replica, with a visible freshness timestamp
just-saved account settings primary
authorization or inventory decision authoritative transaction with concurrency control

The last row needs more than fresh routing. Two transactions can both read the same current stock before either changes it. Use a conditional update, lock, or suitable isolation for the business decision. Replication policy does not replace transactional correctness.

A Timer Is a Heuristic

Some applications send a user's reads to the primary for a few seconds after a write. This can be useful load management, but it is not proof that a replica caught up.

An incident can push lag beyond the timer. A second device may not carry the routing hint. A shared cache may still hold the previous representation.

If you use timed routing, document the behavior as a best-effort experience. Keep strict read-after-write paths on an authoritative source or use an explicit progress check.

Wait for a Replay Position When Needed

PostgreSQL exposes WAL positions through functions including pg_current_wal_lsn() on the primary and pg_last_wal_replay_lsn() on a standby. Their definitions are in the administration functions reference.

One possible application protocol is:

commit the write on the primary
capture a WAL position on that primary after commit
carry it as an opaque consistency token
choose a replica and wait until its replay position reaches the token
start a fresh read on that same replica
fall back to the primary if the bounded wait expires

Capturing after commit may include unrelated newer work, so it can require extra waiting. Do not capture before commit and assume the token covers that transaction. Validate tokens, cap waits, and handle primary changes explicitly; positions need a compatible replication history to be meaningful.

Keep the progress check and read pinned to the same replica. A load balancer sending the read elsewhere invalidates the check. Start a fresh snapshot too: an older transaction snapshot can remain stale after replay has advanced.

Synchronous Does Not Always Mean Visible

PostgreSQL's remote_apply mode waits for the configured synchronous standby set to replay the commit. Other durability acknowledgements do not necessarily establish query visibility. Even with remote_apply, an arbitrary replica outside that set may lag. The synchronous replication guide covers this distinction.

Measure lag and user-visible stale reads, and budget primary capacity for fallback traffic. When replicas fall behind, routing every read to an undersized primary can turn a freshness problem into an availability problem.

Choose replicas for reads whose contract allows them. For the customer who just saved an address, show the state you actually accepted.