Overview
This page is the atomic definition. Read replica routing patterns live at read-replica and postgres.
Definition
Replication lag is the measurement of how far behind a replica database is relative to the primary at any moment. In PostgreSQL streaming replication, the primary writes changes to its write-ahead-log and streams WAL records to standbys. The replica applies those records through a recovery process. Lag can be measured in bytes (pg_replication_slots or pg_stat_replication.replay_lag) or in wall-clock time (sent_lsn - replay_lsn converted to seconds). Causes of lag: the replica’s I/O or CPU cannot keep up with the primary’s write rate; network bandwidth is insufficient; long-running queries on the replica block WAL replay (in hot standby mode); or replication slots accumulate WAL that blocked replicas have not consumed, growing disk usage on the primary. Lag means reads from the replica return stale data, which violates read-your-writes consistency if a user writes on the primary and immediately reads from a replica. Applications that cannot tolerate any lag must route reads to the primary; applications that tolerate some staleness can accept a lag budget.
When it applies
Monitor replication lag continuously. Alert at lag thresholds that exceed the application’s staleness tolerance. For financial or inventory systems, that threshold may be near zero. For analytics read replicas, minutes of lag may be acceptable. Never allow unbounded lag; WAL accumulation from a stalled replica can fill primary disk.
Example
An analytics dashboard reads from a replica. The replica is 8 seconds behind. A user updates their profile and reloads the page. The dashboard shows the old profile because the write has not replicated yet. Fix: route profile reads to the primary, analytics reads to the replica.
Related concepts
- read-replica - the destination that experiences lag; used to offload read traffic.
- write-ahead-log - the WAL stream that replication transmits from primary to replica.
- eventual-consistency - replication lag is the mechanism behind eventual consistency in distributed databases.
- postgres - PostgreSQL’s
pg_stat_replicationview exposes lag metrics.
Citing this term
See Replication Lag (llmbestpractices.com/glossary/replication-lag).