Replication

Active contributors: antirez, Oran Agra, Binbin, debing.sun.

Purpose

Redis replication is a primary→replica streaming model: the master sends a byte stream of write commands to each replica. Replicas apply the stream verbatim. There is no quorum, no consensus — replication in Redis is best-effort by design. Ordering, however, is strict: a replica's state is the result of the master's commands applied in the same order.

Source layout

A single 5,452-line file: src/replication.c. Key sections:

• The master side: replicationFeedReplicas, the replication backlog, replica handshake, full-sync orchestration.
• The replica side: connectWithMaster, the PSYNC state machine, RDB load, command stream replay.
• Diskless and rdbchannel-specific paths.
• Failover commands (REPLICAOF, FAILOVER, REPLCONF).

Concepts

Concept	Meaning
Replication ID	A 40-byte hex string identifying a specific master "history". Generated on master boot and every full sync.
Replication offset	A monotonic byte counter that increments by replication_feed_size per command propagated. Both master and replicas track it.
Replication backlog	A circular buffer (server.repl_backlog) holding the recent replication stream so a reconnecting replica can do partial sync without a full sync.
PSYNC2	Partial sync. A replica reconnects with PSYNC <repl_id> <offset> and the master either ACKs with +CONTINUE (resume from offset) or +FULLRESYNC (must do full sync).
Full sync	RDB transfer + queued commands written since the BGSAVE started. Three transports: disk-backed, diskless socket-stream, and rdbchannel (two-socket).

The full-sync flow (disk-backed)

sequenceDiagram
    participant Replica
    participant Master
    Replica->>Master: TCP connect
    Master->>Replica: +OK
    Replica->>Master: PING
    Master->>Replica: +PONG
    Replica->>Master: REPLCONF listening-port / capa / ip-address
    Master->>Replica: +OK
    Replica->>Master: PSYNC ? -1
    Master->>Replica: +FULLRESYNC <repl_id> <offset>
    Master->>Master: BGSAVE (forks child, writes dump.rdb)
    Master->>Replica: $<size>\r\n<RDB bytes>\r\n
    Master->>Replica: ... live commands buffered during BGSAVE ...
    Replica->>Replica: load RDB
    Replica->>Master: REPLCONF ACK <offset> (every second)

After the RDB is loaded, the replica is "online" and just keeps applying the live command stream. The master tracks the replica's offset via the periodic REPLCONF ACK.

Diskless replication

Set repl-diskless-sync yes to skip writing the RDB to disk. The forked child writes the RDB straight to the socket(s). Multiple replicas can join the same fork if they connect within repl-diskless-sync-delay ms.

Trade-off: if one replica disconnects mid-RDB, it must restart from the beginning of the next BGSAVE. With disk-backed sync, multiple replicas can read the same on-disk file at their own pace.

rdbchannel replication

Introduced in 2024. The master uses one TCP connection for the live command stream and a second for the RDB transfer. This means:

• The replica can keep applying live commands during the RDB load, narrowing the replication lag window.
• The master doesn't have to buffer commands during BGSAVE — they go straight on the live channel.

Set repl-rdb-channel yes (and the symmetric flag on the replica) to opt in. Implementation is in src/replication.c; see tests/integration/replication-rdbchannel.tcl for the protocol details.

The replication backlog

A ring buffer of size repl-backlog-size bytes (default 1 MB; common to set to 64 MB or more). The master writes every propagated command to the backlog as well as to each replica's output buffer. When a replica reconnects with PSYNC <id> <offset>, the master computes how far back offset is from the current write position; if it is still within the backlog, partial sync; otherwise full sync.

Sizing the backlog correctly is a tuning choice: too small and brief disconnects force full syncs; too large and you waste memory.

Replica behaviour

State	Behaviour
Disconnected	The cron tries to reconnect every repl-ping-replica-period seconds.
Handshaking	Negotiating PSYNC.
Receiving RDB	Storing the RDB to disk or applying directly (diskless).
Loading RDB	The dataset is being deserialised. The replica refuses commands except INFO, PING, REPLCONF.
Online	Applying the live stream. ACKs offsets every second.

Failover

Manual failover is via FAILOVER TO <addr> [PORT n] [TIMEOUT m] [FORCE]. The master:

1. Demotes itself to a replica of the chosen replica.
2. Promotes the chosen replica to master.
3. The other replicas re-handshake with the new master.

This is a planned, no-data-loss failover when run against a healthy cluster. For unplanned failures, see Sentinel for sentinels, or the cluster's automatic failover (in src/cluster_legacy.c/src/cluster_asm.c) for cluster mode.

REPLICAOF NO ONE (and the legacy SLAVEOF NO ONE) promotes a replica to standalone. REPLICAOF <host> <port> reconfigures a replica to a different master, triggering a fresh full sync.

Replication-related configs

Option	Purpose
replicaof <host> <port>	Configure as a replica at startup.
masterauth <pass>	Password to use when connecting.
replica-serve-stale-data yes	Keep serving on the replica even if the master link is down.
replica-read-only yes	Reject writes on the replica. Default yes.
repl-diskless-sync	Diskless full sync.
repl-diskless-sync-delay	Wait window to bundle multiple replicas into one fork.
repl-rdb-channel	Enable the rdbchannel two-socket scheme.
repl-backlog-size, repl-backlog-ttl	Backlog dimensions.
repl-ping-replica-period	Master heartbeat interval.
repl-timeout	When a peer's ACK is overdue.
client-output-buffer-limit replica ...	Per-replica output buffer caps.
min-replicas-to-write, min-replicas-max-lag	Refuse writes if not enough replicas are connected and lagging within budget.

What can a replica do that breaks invariants

A replica must not write to its own dataset (except by replaying the master). The two notable edge cases:

• replica-read-only no — let clients write directly to the replica. Writes do not propagate; on the next full sync the replica's local writes are wiped. Useful for caches.
• Module commands marked MAY_REPLICATE — modules must opt in to make a command propagate.

Where to start modifying

• Tweak the PSYNC state machine — search for replicaTryPartialResynchronization in src/replication.c.
• Add a new REPLCONF subcommand — add to the replconfCommand switch.
• Tune backlog accounting — feedReplicationBuffer, freeReplicationBacklogRefMemAsync.
• Diagnose lag — INFO replication exposes per-replica lag and offset; the cron in src/server.c updates them.

Related pages

• Persistence — RDB is the full-sync transport.
• Cluster — cluster mode replicates between primaries and replicas of the same shard.
• Sentinel — Sentinel orchestrates replication failover.