diagrams
Database

Primary Replica Sync

Primary replica sync is the message-level protocol by which a primary database node ships its write-ahead log (WAL) or binary log entries to one or more replica nodes, keeping their data in step with the primary.

diagram.mmd — sequence
Edit in Graphlet →
Primary Replica Sync sequence diagram
About Source

Primary replica sync is the message-level protocol by which a primary database node ships its write-ahead log (WAL) or binary log entries to one or more replica nodes, keeping their data in step with the primary.

This sequence diagram traces a single write operation from client submission through to replica acknowledgment. The client sends a write to the Primary. The primary validates the transaction and appends the change to its Write-Ahead Log (WAL) before applying the change to its local storage. This ordering is critical: logging before applying means the change can be replayed if the primary crashes mid-write.

Once logged, the primary sends the log segment to the Replica. In PostgreSQL streaming replication this happens via a persistent replication slot connection; in MySQL it is the binlog dump protocol. The replica writes the received segment to its own standby WAL and sends back an acknowledgment containing its current log sequence number (LSN). The primary tracks each replica's LSN to know how far behind it is — this is the replication lag.

In synchronous mode (shown in the diagram), the primary waits for this acknowledgment before replying to the client. This guarantees that at least one replica holds the data even if the primary is lost immediately after the commit. In asynchronous mode, the primary skips the wait and replies to the client before the replica has confirmed receipt.

Understanding this flow matters when reasoning about failover. If the primary fails before an async replica acknowledges the last WAL segment, those writes are lost. Tools like Patroni or AWS RDS Multi-AZ enforce synchronous replication to a standby to make the Database Failover process lossless. See Database Replication for the broader topology this sync process operates within.

Free online editor
Edit this diagram in Graphlet
Fork, modify, and export to SVG or PNG. No sign-up required.
Open in Graphlet →

Frequently asked questions

Primary replica sync is the message-level protocol by which a primary database node ships Write-Ahead Log (WAL) or binary log entries to one or more replica nodes, keeping replica data in step with the primary. It is the underlying mechanism that drives all replication topologies.
The client sends a write to the primary. The primary appends the change to its WAL before applying it locally. It then ships the WAL segment to the replica over a persistent replication connection. The replica writes the segment to its standby WAL and sends back an acknowledgment containing its current log sequence number (LSN). In synchronous mode the primary waits for this acknowledgment before replying to the client; in asynchronous mode it replies immediately.
Replication lag is the difference between the primary's current LSN and the replica's applied LSN. It grows when the primary generates WAL faster than the replica can apply it — due to high write volume, slow replica I/O, network congestion, or long-running queries on the replica blocking log application. In PostgreSQL, `pg_stat_replication` shows each replica's sent, written, flushed, and replayed LSN for precise lag measurement.
In synchronous replication, the primary holds the client's COMMIT acknowledgment until at least one replica confirms it has durably written the WAL segment. This guarantees zero data loss if the primary fails immediately after commit. In asynchronous replication, the primary acknowledges COMMIT before the replica confirms receipt, allowing the replica to lag behind and potentially lose the most recent writes if the primary fails.
mermaid
sequenceDiagram participant Client participant Primary as Primary DB participant WAL as Write-Ahead Log participant Replica as Replica DB participant StandbyWAL as Standby WAL Client->>Primary: Write transaction Primary->>WAL: Append log entry (LSN 1042) WAL-->>Primary: Logged Primary->>Primary: Apply change to storage Primary->>Replica: Ship WAL segment (LSN 1042) Replica->>StandbyWAL: Write received segment StandbyWAL-->>Replica: Written Replica->>Replica: Apply change to storage Replica-->>Primary: Ack LSN 1042 Primary-->>Client: Write confirmed note">Note over Primary,Replica: Replication lag = 0 (synchronous mode)
Copied to clipboard