You send reads to PostgreSQL read replicas. A user updates their profile, reloads, and sees the old data. Why, and how do you guarantee read-your-writes?

The replica has not received the write yet. This delay is called replication lag.

PostgreSQL streaming replication is asynchronous by default. The primary commits the change and returns success first. Then it sends the WAL (Write-Ahead Log: the record of every change) to the replicas, and they apply it a moment later. The lag is usually milliseconds, but it can be seconds or more under heavy load. If a read goes to a replica that is behind, it returns the old row.

Ways to get read-your-writes (a user always sees their own changes):

• Send a user's reads to the primary right after that user writes. For example, do it for a few seconds after the write, or for the rest of the request.
• Save the WAL position of the write with pg_current_wal_lsn(). Read from a replica only after it has replayed past that point. Check this with pg_last_wal_replay_lsn() on the replica.
• Use synchronous replication with remote_apply. This also works, but it makes every commit slower.

Watch the lag with pg_stat_replication on the primary. Keep reads that must be fully up to date on the primary, for example a balance check before a payment.