Redis upgrade and migration with practical examples: practical implementation guide

Intro

Upgrading or migrating Redis should improve security, stability, and performance without disrupting your applications. The risk is not the new version itself; it is unplanned change. This guide shows how to plan and execute Redis upgrades with low risk, verify every step, and safely roll back if needed. You will inventory your environment, choose a safe path, run through practical examples for standalone, Sentinel, and Cluster, and close with diagnostics, failure modes, and a repeatable checklist.

Version and Environment Inventory

Strong upgrades begin with clear facts. Capture these before you touch production.

Prerequisites and access

• Shell access to Redis hosts.
• Ability to update configuration and restart Redis under a maintenance window if required.
• Access to DNS or service discovery for client cutover.
• Sufficient disk space for an extra full snapshot (plan for at least dataset_size * 1.5 free space).

Inventory commands (run on each node)

• Identify binary version:
• redis-server -v
• Server details (build, config file path):
• redis-cli INFO server
• Persistence mode and snapshot schedule:
• redis-cli CONFIG GET appendonly
• redis-cli CONFIG GET save
• Dataset size and keyspace:
• redis-cli INFO memory
• redis-cli INFO keyspace
• Replication and role:
• redis-cli INFO replication
• redis-cli ROLE
• Command mix and throughput:
• redis-cli INFO commandstats
• redis-cli INFO stats

Topology classification

• Standalone: one primary, optionally replicas.
• Sentinel: high-availability sentinel-managed primaries and replicas.
• Cluster: sharded deployment with masters and replicas.

Application considerations

• Client libraries and connection strings (auth, TLS, timeouts, retry policies).
• Key eviction policy and memory limits (CONFIG GET maxmemory, maxmemory-policy).
• Allowed downtime and cutover strategy (DNS switch, connection reuse, or orchestrated failover).

Backups and integrity checks

• Create a clean RDB snapshot:
• redis-cli BGSAVE
• Verify existence and timestamp in the dir from CONFIG GET dir
• If AOF is enabled, validate it offline on a copy:
• redis-check-aof --fix appendonly.aof (run on a copy, not in place)
• Validate RDB offline on a copy:
• redis-check-rdb dump.rdb

Safety toggles to note

• stop-writes-on-bgsave-error should be yes for safety (CONFIG GET stop-writes-on-bgsave-error).
• appendfsync default everysec is a balanced choice for durability vs. performance.

Safe Configuration Path

Choose an approach that matches your topology and risk tolerance. The following patterns cover most real-world needs.

Constructed comparison table (choose based on your environment):

Notes

• Values are constructed examples. Measure in your environment.
• Prefer replica-based methods for low risk and simple rollback.

Configuration considerations across methods

• Keep authentication and ACLs identical on old and new hosts before cutover (ACL LIST, ACL GETUSER, ACL SETUSER).
• Match persistence mode (RDB/AOF) during replication to avoid surprises at startup.
• Ensure repl-backlog-size is sufficient for the replication window during migration to prevent full resyncs.
• Use low DNS TTL (constructed example: 30s) for smoother client cutover.

Practical Walkthroughs

This section provides concrete steps for common scenarios. Adjust hostnames, ports, and paths to your environment.

Walkthrough A: Standalone upgrade using a replica (low downtime)

Scenario (constructed example): Upgrade Redis 6.2 on host old-redis:6379 to Redis 7.x on host new-redis:6379 with a 5-second cutover.

1. Prepare target with matching config

• Copy redis.conf from old to new and update only paths and bind addresses as needed.
• Ensure authentication and ACLs are the same before replication.

1. Start the new Redis as a replica of the old

• On new-redis, set replicaof and start Redis 7.x:
• In redis.conf on new-redis: replicaof old-redis 6379
• Start service (use your OS service manager)

1. Verify full sync and steady-state replication

• On new-redis:
• redis-cli INFO replication
• Expected: role: slave, master_link_status: up, master_sync_in_progress:0
• Check replication offset alignment:
• On both nodes: redis-cli INFO replication | grep -E "offset|slave_repl_offset"

1. Optional read-only sampling

• Run read-only checks against the replica to validate data presence and basic latency:
• redis-cli -h new-redis DBSIZE
• redis-cli -h new-redis --latency-history --csv --raw (brief observation window)

1. Cutover with a short write pause

• Goal: avoid divergence during switch.
• On old-redis, pause new writes briefly:
• redis-cli CLIENT PAUSE 3000 WRITE
• Promote the replica to master:
• redis-cli -h new-redis REPLICAOF NO ONE
• Re-point old master to follow the new master (keeps rollback easy):
• redis-cli -h old-redis REPLICAOF new-redis 6379
• Update clients (prefer DNS switch if used). Keep TTL low in advance (constructed example: 30s).

1. Unpause writes and validate

• On old-redis: redis-cli CLIENT UNPAUSE
• Confirm roles:
• redis-cli -h new-redis ROLE (expect master)
• redis-cli -h old-redis ROLE (expect slave)
• Confirm write success on new-redis:
• redis-cli -h new-redis SET upgrade: smoke 1
• redis-cli -h new-redis GET upgrade: smoke

Walkthrough B: Redis Cluster rolling upgrade (per-shard failover)

Scenario (constructed example): Cluster with 3 masters, each with 1 replica; upgrade from 6.x to 7.x without full-cluster downtime.

1. Pick one shard pair (master M1, replica R1)

• Upgrade the replica first to 7.x (stop service, upgrade binary, start service).
• Verify it rejoins and syncs: redis-cli -p <R1-port> INFO replication

1. Promote the upgraded replica

• On R1: redis-cli -p <R1-port> CLUSTER FAILOVER
• Wait until R1 becomes master and M1 becomes replica. Verify with ROLE on both.

1. Upgrade the old master (now a replica)

• Stop M1, upgrade to 7.x, start it and let it sync as replica.

1. Repeat per shard

• Move to shard 2 (M2/R2), then shard 3, repeating the same pattern.

1. Post-upgrade checks

• redis-cli --cluster check <any-node-host: port>
• Confirm number of masters, replicas, and slot coverage.

Walkthrough C: Cross-environment migration (same version or version bump)

Scenario (constructed example): Move Redis from DC-A to DC-B with a version bump, minimal downtime.

1. Seed a replica across environments

• In DC-B, start Redis with replicaof DC-A primary.
• Ensure firewall rules and latency/bandwidth are acceptable.

1. Observe steady replication for at least one business cycle

• Validate memory usage, replication offsets, and latency stability.

1. Schedule cutover

• Lower DNS TTL well before cutover.
• Pause writes on DC-A for a few seconds: CLIENT PAUSE 3000 WRITE
• Promote DC-B: REPLICAOF NO ONE
• Reconfigure DC-A to follow DC-B: REPLICAOF <DC-B> 6379
• Update DNS to DC-B.

1. Monitor and unpause

• Verify application reconnects and command success.
• Unpause writes on DC-A and keep it as hot standby temporarily for rollback.

Verification and Diagnostics

Verification proves the upgrade is correct, not just complete.

Core checks and expected results

| Snapshot present | ls $(redis-cli CONFIG GET dir | tail -1)/dump.rdb | Recent timestamp, non-zero size | | AOF enabled (if used) | redis-cli CONFIG GET appendonly | appendonly yes or no as desired | | Dataset size parity | redis-cli DBSIZE | Same or greater key count after cutover | | Command mix stable | redis-cli INFO commandstats | No unexpected missing commands | | Latency baseline | redis-cli --latency -h <host> -p <port> | Similar to or better than pre-upgrade |

Operational diagnostics

• INFO latency, memory, clients: baselines of accepted ranges.
• SLOWLOG GET 128: ensure no new slow commands introduced by upgrade.
• LATENCY DOCTOR: quick triage if spikes appear.
• MONITOR is powerful but heavy; avoid on production during peak.

Synthetic probing (use sparingly)

• Against a non-critical window, a small synthetic probe can reveal regressions:
• redis-benchmark -h <host> -p <port> -n 5000 -c 10 -t get, set
• Keep tests short and low concurrency in production.

Application-level verification

• Validate connection, basic commands, and error handling from one app instance before global rollout.
• Constructed Node.js connectivity smoke test:

// Node.js example using ioredis (constructed snippet)
const Redis = require('ioredis');
const r = new Redis({ host: 'new-redis', port: 6379, retryStrategy: null });
(async () => {
  await r.set('upgrade: node: smoke', 'ok', 'EX', 60);
  const v = await r.get('upgrade: node: smoke');
  console.log('Smoke value:', v);
  await r.quit();
})();

Capacity and memory headroom

• After cutover, ensure used_memory < maxmemory * 0.7 (constructed guideline) to leave space for replicas and bursts.
• Watch eviction metrics: INFO stats -> evicted_keys should not climb unexpectedly.

Failure Modes and Recovery

Expect the following failure modes and prepare responses before starting.

1. Replica never catches up (bandwidth or backlog insufficiency)

• Symptom: master_link_status flaps; master_sync_in_progress repeats full syncs.
• Action: increase repl-backlog-size, ensure network stability. Optionally seed with an RDB copy to reduce initial sync cost:
• Stop target, copy dump.rdb from source, start target as replica.

1. Data divergence during cutover

• Symptom: keys missing/overwritten on new master post-cutover.
• Action: use CLIENT PAUSE WRITE during cutover to drain writes. If divergence is detected quickly, roll back: promote old master and re-point clients.

1. AOF/RDB corruption on startup (target)

• Symptom: Redis refuses to start or crashes reading persistence files.
• Action: do not repair in place. On a copy, run redis-check-rdb or redis-check-aof. Replace corrupted file with a known-good snapshot. Keep old master serving while you recover.

1. ACL or auth mismatch

• Symptom: clients receive NOAUTH or NOPERM after cutover.
• Action: export ACLs from source before migration and import them on target:
• Source: redis-cli ACL LIST > acls.txt
• Target: apply equivalent ACL SETUSER commands.

1. Performance regression (latency spikes)

• Symptom: higher p50/p99 latency, dropped connections.
• Action: compare CONFIG, especially maxmemory-policy, I/O and persistence settings. Test both appendonly states (on/off) if changed. Roll back if latency is unacceptable and root cause is unknown.

1. Cluster slot coverage issues after rolling upgrade

• Symptom: redis-cli --cluster check shows unassigned slots or failing nodes.
• Action: re-add replicas if needed, run redis-cli --cluster fix <node>. Ensure each master has at least one healthy replica before proceeding.

1. Unexpected command behavior

• Symptom: new or deprecated behavior affects application logic.
• Action: validate command mix via INFO commandstats; add targeted integration tests for critical commands. If necessary, lock to a known-safe compatibility config option when available, or roll back while you adapt.

Rollback playbook (standalone or Sentinel)

• Keep the old master running as a replica after cutover for fast rollback.
• To roll back within minutes:

1. Pause writes on new master: CLIENT PAUSE 3000 WRITE
2. Promote old node back to master: REPLICAOF NO ONE (on old)
3. Point new node to follow old: REPLICAOF <old> 6379
4. Update DNS back to old master
5. Unpause writes on old master

Rollback playbook (Cluster)

• Reverse the most recent shard failover:

1. On the former master (now replica), ensure it is upgraded and healthy
2. CLUSTER FAILOVER on the replica you wish to promote
3. Verify slot coverage and client connectivity

Success criteria for recovery

• Clients reconnect within the expected TTL.
• Command error rates and latencies return to pre-change baselines.
• Replication re-establishes cleanly in the new topology.

Operations Checklist

Use this checklist as a repeatable runbook.

Planning

• Define the target version and changelog items relevant to your workload.
• Choose a migration pattern (replica promotion is the default for low risk).
• Set a measurable success definition (constructed example: p95 latency within 10% of baseline and zero data loss).
• Lower DNS TTL ahead of cutover if using DNS-based switching.

Preflight

• Capture current INFO outputs and configs for diff and rollback.
• Create and verify an RDB snapshot (and validate AOF if enabled).
• Ensure free disk space >= 1.5x dataset on both source and target.
• Align ACLs and authentication on target with source.
• Verify network paths and firewall rules for replication.

Execution

• Start target as replica of source; verify full sync completes.
• Observe replication offsets and stability under typical load.
• Optionally run read-only validation queries on the replica.
• Announce a brief cutover window.
• Pause writes briefly, promote the replica, re-point the former master to follow the new master.
• Update DNS or connection endpoints.

Verification

• Confirm target role: master. Confirm clients reconnected.
• Check DBSIZE parity and sample key reads.
• Monitor latency (redis-cli --latency) for a few minutes.
• Review SLOWLOG and INFO commandstats for anomalies.

Stabilization

• Keep the former master as a replica until you are confident in stability.
• Take a fresh snapshot on the new master.
• Restore normal DNS TTLs.

Post-mortem and hardening

• Record timing, downtime, and any issues.
• Adjust repl-backlog-size and snapshot cadence as needed.
• Update the runbook with lessons learned.

Conclusion

Upgrading or migrating Redis can be predictable, fast, and safe when you inventory your environment, choose a replica-first path, validate with concrete checks, and keep a tested rollback ready. Start with a small, inspectable pilot to confirm your approach, then scale out with confidence using the same steps. With the walkthroughs, diagnostics, and checklists in this guide, you can reduce risk while capturing the benefits of newer Redis versions.