A-7 — Master-Replica Replication: PSYNC, Replication Buffer, and Lag

Who this module is for: You are running Redis with replicas for read scaling or failover, but you have not understood what happens inside a replication relationship — how data flows, what happens when a replica reconnects after a disconnect, and when replication lag becomes a data consistency crisis. This module covers the full replication model.

The Replication Model

Redis uses asynchronous replication. The primary processes a write command, sends the command to connected replicas, and returns OK to the client — without waiting for replicas to acknowledge. Replicas apply commands in the order they are received, maintaining an eventually consistent copy of the primary's dataset.

Consequence: There is always a window (typically < 1ms, but potentially much longer under load or network issues) during which a write exists on the primary but not on replicas. If the primary fails in this window, the write is lost.

Setting Up Replication

Authentication for replication:

Initial Sync: Full Resync

When a replica connects to a primary for the first time (or after a long disconnection), it performs a full resync:

Memory impact: During full resync, the primary uses extra RAM for:

• The BGSAVE fork + copy-on-write pages
• The replication output buffer (buffering commands written during RDB transfer)

A large primary with a high write rate can use 2–3× its normal RAM during a full resync. Size your primary to handle this.

Incremental Resync: PSYNC with Replication ID and Offset

After initial sync, the replica streams commands from the primary continuously. Each command changes the replication offset — a byte count of how much data has been replicated.

Redis assigns each primary a replication ID (a random 40-character hex string). When a replica reconnects after a brief disconnect:

The Replication Backlog

The replication backlog is a circular buffer on the primary that holds recent write commands. Its size is configurable:

If a replica disconnects and reconnects within the time it takes to fill the backlog, it can do a partial resync. If the backlog has rolled over (the commands since the disconnect are no longer in the buffer), a full resync is required.

Size your backlog appropriately. At 100MB/s of write throughput, a 1MB backlog fills in 10ms. A replica that disconnects for even 1 second will require a full resync. Set the backlog to at least 60 seconds × write rate in bytes:

This trades memory (the backlog lives in RAM) for resilience to brief replica disconnections.

Monitoring Replication

On the primary:

lag — seconds since the replica last sent a REPLCONF ACK. A lag of 0 or 1 is healthy. Growing lag is a warning.

On a replica:

master_link_status: down means the replica is disconnected. master_sync_in_progress: 1 means a full resync is underway.

Measure replication lag in bytes: The offset difference between master_repl_offset and slave_repl_offset is the lag in bytes. Convert to time: lag_bytes / write_rate_bytes_per_second.

Replica Configuration Options

min-replicas-to-write

This setting prevents the primary from accepting writes when it cannot reach enough replicas:

With these settings, if all replicas disconnect (network partition, all replica crashes), the primary stops accepting writes after 10 seconds. This prevents a split-brain scenario where the primary continues writing data that will be lost when the partition heals.

Trade-off: This reduces availability (primary stops during replica outage). For systems where data loss is unacceptable, this is the correct trade. For systems where availability is more important than durability, leave at min-replicas-to-write 0.

Read from Replicas

Route read-heavy, latency-tolerant queries to replicas to reduce primary load:

What must NOT be read from replicas:

• Session tokens (replication lag → "token not found" → false logout)
• Lock state (lag → two clients think they hold the lock)
• Rate limit counters (lag → allowing more requests than permitted)
• Any coordination state where stale data causes incorrect decisions

Safe to read from replicas:

• Cached content (product data, blog posts, configuration)
• Analytics/reporting queries
• Historical data that changes slowly

Replication and Lua Scripts

Lua scripts executed on the primary are replicated to replicas in one of two ways:

• Script replication (default until Redis 7.0): The entire EVAL command is replicated. Replicas re-execute the script. Non-deterministic scripts (using TIME, SRANDMEMBER) produce different results on replicas — a data divergence bug.

• Effect replication (Redis 3.2+, default in Redis 7.0): Only the write commands issued by the script are replicated. Deterministic regardless of script behaviour.

If your Lua scripts use non-deterministic functions, ensure effect replication is enabled to prevent replica divergence.

Diskless Replication

Full resync normally generates an RDB file on disk, then streams it. Diskless replication streams the RDB directly from memory to the replica socket — no disk write:

Diskless replication is faster when disk I/O is the bottleneck (many replicas connecting simultaneously, or a slow disk). The memory footprint is similar to disk-based sync (the RDB data must be held in memory to stream it).

Common Replication Problems

Growing Replication Lag

Cause: Replica cannot apply commands as fast as the primary sends them.

Symptoms: slave.lag increases steadily in INFO replication. Replica's slave_repl_offset falls further behind master_repl_offset.

Diagnosis:

• Check replica CPU — if at 100%, the replica is compute-bound on command application
• Check network bandwidth between primary and replica
• Check if the primary is issuing very large commands (MSET with thousands of keys) that take time to apply

Fix: Vertical scaling of the replica, or reduce primary write rate by batching or throttling.

Replica Requires Full Resync After Brief Disconnect

Cause: Replication backlog too small — the commands since the disconnect are no longer in the buffer.

Fix: Increase repl-backlog-size. Calculate required size: max_disconnection_time_seconds × write_rate_bytes_per_second.

Client Reading Stale Data from Replica

Cause: Reading coordination-critical data from a replica with non-trivial lag.

Fix: Route coordination reads to the primary. See P-9 (session management) and A-6 (SupraScan) for the correct pattern.

Summary

• Redis replication is asynchronous — primary acknowledges writes before replicas confirm receipt; data loss is possible in the replica lag window
• Full resync (PSYNC with ? offset): replica loads an RDB snapshot from the primary — happens on first connect or after falling too far behind
• Partial resync (PSYNC with known replication ID + offset): replica catches up from the replication backlog — fast; only possible if offset is still in the backlog
• Size repl-backlog-size = max_expected_disconnect_seconds × write_rate — too small causes unnecessary full resyncs
• Monitor slave.lag (seconds) and the offset delta (bytes); alert when lag exceeds 5 seconds
• min-replicas-to-write prevents writes when replicas are disconnected — choose availability vs durability
• Route read-heavy, latency-tolerant queries to replicas; always read coordination state from the primary
• Effect replication prevents non-deterministic Lua script divergence on replicas

Next: A-8 — Redis Sentinel: Quorum, Failover, and Split-Brain Prevention — the automatic failover system that promotes a replica to primary and reconfigures clients when the primary goes down.