Guide to Setting Up Redis Primary-Replica Replication.

Guide to Setting Up Redis Primary-Replica Replication

Redis replication is a fundamental pattern for achieving high availability, data redundancy, and read scalability. By setting up a primary (formerly called master) and one or more replicas (formerly called slaves), you ensure that data written to the primary is automatically copied to all connected replicas.

This guide provides a comprehensive, step-by-step tutorial on configuring Redis primary-replica replication. We will cover the essential configuration directives, dynamic configuration methods, and critical monitoring steps necessary to build a robust and reliable Redis deployment.

1. Understanding Redis Replication Fundamentals

Redis replication is asynchronous (meaning the primary doesn't wait for the replica to acknowledge writes), allowing for high performance. It operates primarily through two phases: initial synchronization and continuous synchronization.

Full Synchronization (SYNC)

When a replica connects to a primary for the first time, or after a network interruption that prevents partial resynchronization, a full synchronization occurs:

The replica sends a PSYNC command to the primary.
The primary starts a background saving process to generate an RDB snapshot file (.rdb).
The primary buffers all new write commands received while the RDB is being created.
Once the RDB file is complete, the primary sends it to the replica.
The replica loads the RDB file into memory.
Finally, the primary sends all buffered write commands to the replica to catch up.

Partial Resynchronization (PSYNC)

Redis 2.8+ supports partial resynchronization. If the link between the primary and replica drops briefly, the replica can request only the missing commands since the link broke, using the replication backlog buffer (a configurable circular buffer on the primary).

2. Prerequisites and Setup

Before configuring replication, ensure you have at least two separate Redis instances running (or separate configurations running on different ports on the same server for testing).

For this guide, we assume the following setup:

Instance	Role	IP Address	Port	Configuration File
Primary	Primary	192.168.1.100	6379	`redis-primary.conf`
Replica 1	Replica	192.168.1.101	6380	`redis-replica-1.conf`

Step 2.1: Configure the Primary Instance

Ensure your primary instance is ready to accept connections from the replicas and is configured to manage persistence (RDB or AOF) if required for the primary's own stability.

Crucial Primary Settings:

Binding: Ensure the primary is bound to a public IP address or 0.0.0.0 if running across multiple machines. If using firewalls, ensure port 6379 is open for the replica IPs.
Persistence: While not strictly required for replication itself, enabling RDB/AOF is strongly recommended for primary data persistence.

# redis-primary.conf
port 6379
bind 0.0.0.0 # Binds to all interfaces (necessary for external replicas)
# Enable RDB persistence
save 900 1
save 300 10
save 60 10000

Step 2.2: Configure the Replica Instance

The core of setting up a replica lies in the replicaof directive. This tells the instance which primary it should synchronize its data with.

Crucial Replica Settings:

Port: Use a different port if running on the same machine.
Replication Directive: Use replicaof or slaveof (the legacy name).

# redis-replica-1.conf
port 6380

# *** Essential Replication Configuration ***
replicaof 192.168.1.100 6379

# Ensure replicas are read-only (default since Redis 5)
replica-read-only yes

# Recommend disabling persistence on replicas if HA is handled by Sentinel/Cluster
# If persistence is needed for quick restarts, keep it enabled.
save ""

Note: If the primary is secured with a password (using requirepass), the replica must be configured with masterauth <password> to authenticate successfully.

3. Implementation Methods

You can implement the replication configuration either by editing the configuration file (redis.conf) and restarting the server, or dynamically using the CONFIG SET command.

Method 3.1: Configuration File (Recommended for Production)

After updating redis-replica-1.conf as shown above, start both instances:

# Start Primary
redis-server redis-primary.conf

# Start Replica 1
redis-server redis-replica-1.conf

Upon startup, Replica 1 will immediately attempt to connect to the primary at 192.168.1.100:6379 and begin the synchronization process.

Method 3.2: Dynamic Configuration

If a Redis instance is already running and you wish to configure it as a replica without a restart, use CONFIG SET via redis-cli.

Connect to the instance you want to convert into a replica (running on port 6380 in our example):

bash redis-cli -p 6380
Execute the replication command:

bash 127.0.0.1:6380> replicaof 192.168.1.100 6379 OK

The instance at 6380 will drop any previous data and initiate a full synchronization (SYNC) with the new primary.

⚠️ Warning: Disabling Replication

To turn a replica back into a standalone primary instance, execute replicaof no one on that instance.

4. Monitoring Replication Status

Monitoring the connection status is vital to ensure data consistency. Use the INFO replication command via redis-cli on both the primary and the replica.

4.1 Checking the Primary Status

Connect to the primary (6379) and check how many replicas are connected and their status:

redis-cli -p 6379 INFO replication

Expected Output Snippet (Primary):

# Replication
role:master
connected_slaves:1
slave0:ip=192.168.1.101,port=6380,state=online,offset=2048,lag=0
master_replid:a9b1c2...
master_replid2:000000...
master_repl_offset:2048

role:master confirms its role.
connected_slaves:1 confirms the replica is seen.
state=online is the desired steady state.
lag=0 (or a very low number) indicates successful synchronous data transfer performance.

4.2 Checking the Replica Status

Connect to the replica (6380) and check the primary link status:

redis-cli -p 6380 INFO replication

Expected Output Snippet (Replica):

# Replication
role:slave
master_host:192.168.1.100
master_port:6379
master_link_status:up
master_sync_in_progress:0
slave_priority:100
slave_read_only:1

role:slave confirms its role.
master_link_status:up confirms the connection is active and healthy.
master_sync_in_progress:0 means the initial synchronization is complete.

5. Replication Best Practices and Optimization

5.1 Replication Read-Only Mode

By default, replicas are read-only (replica-read-only yes). This is a critical safety mechanism. Attempting to write to a replica will result in an error, ensuring data consistency across the cluster.

If you disable read-only mode, any writes to the replica will be local and will be overwritten if the replication link breaks and a full synchronization occurs.

5.2 Optimizing Synchronization Time

If your dataset is very large, the initial SYNC process can be slow. Consider these factors:

Network Bandwidth: Ensure sufficient bandwidth between the primary and replicas for the RDB transfer.
RDB Generation: The primary needs CPU and disk I/O to generate the RDB file. Ensure the server has available resources during sync.
Disable Disk Persistence on Replicas (Optional): If the primary handles all persistence and the replica is only for read scaling, setting save "" on the replica avoids the I/O overhead of writing RDB files, speeding up restarts.

5.3 Security and Network Configuration

It is crucial that the primary does not publicly expose its replication port (6379 or otherwise) to the internet. Configure firewall rules to allow replication traffic only from the designated IP addresses of the replica servers.

5.4 Use Replicas for Read Scaling

The primary benefit of replication is distributing read load. Direct applications that primarily perform read operations to the replica instances, reserving the primary for write operations, improving overall system throughput.

Conclusion

Setting up Redis primary-replica replication is essential for building resilient, high-performance applications. By correctly configuring the replicaof directive and regularly monitoring the link status using INFO replication, you create a foundation for high availability and effective read scaling.

While this guide focuses on the basic setup, production environments often integrate further layers of automation, such as Redis Sentinel for automatic primary promotion and failure detection, or Redis Cluster for automatic partitioning and distribution of data across multiple nodes.