How to Migrate Redis Data with Master Replica Replication Minimal Downtime Guide
Card No. 06·17064 · Updated · Standard formula, shown below
This guide shows you how to migrate Redis data from one server (or cluster) to another with minimal downtime using master-replica replication. You set up the new Redis instance as a replica of the old one, let it catch up, then promote it to master and switch your applications over. This approach typically reduces downtime to just a few seconds, compared to a full dump-and-restore which can take minutes or hours.
What You’ll Need
Access to the old Redis server (source) with admin privileges (to run CONFIG SET, REPLICAOF, etc.)
A new Redis server (target) with Redis installed (same major version or newer is recommended)
Network connectivity between the two servers (port 6379 or your custom port must be open)
If Redis requires a password, have the credentials ready
Ability to restart or reconfigure your application’s Redis connection settings
Optional: a maintenance window for the final switchover, though the goal is to minimize it
Step-by-Step
Prepare the target server. Install Redis on the new machine, configure it with appropriate memory limits, persistence (RDB/AOF) settings, and security (password, firewall). Test that Redis starts and responds to ping.
Backup the source (optional but recommended). Before making changes, take a snapshot of the source data using redis-cli --rdb dump.rdb or by copying the RDB file. This is your safety net if something goes wrong.
Configure the target as a replica. On the target server, run redis-cli REPLICAOF. If the source requires a password, first set it with CONFIG SET masterauth "". If you have a firewall, ensure the target can reach the source.
Monitor replication. On the target, run redis-cli INFO replication. Check that master_link_status:up and master_repl_offset is increasing. The target is now receiving all writes from the source.
Let replication catch up. Wait until the target’s master_repl_offset matches the source’s master_repl_offset (or at least is very close). You can check the source with redis-cli INFO replication to see its offset. This may take seconds or minutes depending on data size.
Stop writes to the source (optional but recommended for consistency). If your application allows, pause write operations briefly. This ensures the offset is stable. Alternatively, you can proceed without stopping writes, but you’ll need to handle the final delta.
Promote the target to master. On the target, run redis-cli REPLICAOF NO ONE. This makes the target a master and stops replication. It now has all the data that was on the source up to the moment of promotion.
Switch your application to the new master. Update your application’s Redis connection string (host/port) to point to the new server. If you use a DNS name, update the DNS record. If you have a load balancer, update the backend.
Verify data integrity. Run a few sanity checks on the new master: redis-cli DBSIZE to see the key count, and spot-check some keys with GET or TYPE. Compare with the source if possible.
Decommission the old server (after a grace period). Keep the old server running for a few days to ensure everything is fine. Once you’re confident, you can shut it down or repurpose it.
Common Mistakes
Forgetting to set masterauth. If the source requires a password, the target will fail to connect. Always set masterauth before calling REPLICAOF.
Not waiting for full sync. Promoting the target before it has caught up will result in data loss. Always check the replication offset.
Switching applications before promotion. If you point your app to the target while it’s still a replica, writes will be rejected (unless you enable replica-writable, which is not recommended).
Ignoring firewall rules. Redis uses TCP port 6379 by default. Ensure the target can connect to the source on that port.
Using different Redis versions. Replication between very different versions may cause issues. Use the same or newer version on the target.
Not testing the switchover. Always practice on a staging environment to avoid surprises.
Tips
Use a maintenance window if possible. Even though downtime is minimal, it’s safer to do the switch during low traffic.
Monitor replication lag. Use redis-cli INFO replication to see the lag in seconds. It should be near zero before promotion.
Consider using Redis Sentinel or Cluster. For automatic failover, you can set up Sentinel to monitor the master and promote a replica automatically. This guide covers manual migration, but Sentinel can automate the promotion step.
Test the new server’s performance. Run a few load tests to ensure it can handle your traffic.
Keep the source RDB file. If you need to roll back, you can restore from the backup.
Use a configuration management tool. If you have multiple instances, automate the process with Ansible, Puppet, or similar.
Troubleshooting
Replication not starting. Check the target’s log (/var/log/redis/redis-server.log) for errors. Common causes: wrong IP/port, firewall, or authentication failure. Test connectivity with redis-cli -h-p ping.
Master link keeps going down. This often indicates network instability or timeouts. Increase repl-timeout on the target. Also check for bandwidth issues if you have a large dataset.
Data mismatch after promotion. If you didn’t wait for full sync, some keys may be missing. You can re-sync by doing a full restart of the target with a fresh RDB from the source, or restore from backup.
Target is read-only after promotion. If you accidentally left replica-read-only enabled, you can disable it with CONFIG SET replica-read-only no, but it’s better to keep it as is and just write normally.
Application cannot connect. Check that the target’s port is open, Redis is running, and the password is correct. Use redis-cli -h -p ping to test.
Promotion fails with “REPLICAOF NO ONE” error. This can happen if the target is not a replica. Check INFO replication to confirm the role.
Frequently Asked Questions
How long does the migration take?
The initial sync time depends on the dataset size and network speed. For a small dataset (a few GB), it might take seconds. For large datasets (tens of GB), it could take minutes. The switchover itself takes less than a second.
Can I do this without stopping writes?
Yes, you can keep writes flowing during the sync. The target will catch up to the source’s offset. When you promote, there will be a tiny window where writes are not accepted (the time between promotion and app switch). To minimize this, you can stop writes briefly during promotion.
What happens to data written to the source after promotion?
Once you promote the target, the source is no longer the master. Any writes to the source after that point will be lost (unless you set up replication in the opposite direction). That’s why you must switch your application to the new master as soon as possible.
Can I use this method to migrate to a Redis Cluster?
Yes, but it’s more complex. You would need to set up the cluster first, then use the cluster’s replication features to migrate each shard. This guide covers single-instance migration; for clusters, consider using Redis Cluster’s resharding tools or a third-party tool like redis-shake.
Is it safe to use the same Redis version on both servers?
Yes, using the same version is safest. If you must use different versions, use a newer version on the target. Replication from an older master to a newer replica is generally supported.
What if I need to roll back?
If you have the source server still running, you can simply point your application back to it. If you shut it down, you can restore from the RDB backup you took in step 2. Note that any writes made to the new master after promotion will be lost.