Engula

Docs
Docs

Redis 6.x → 7.2 rolling upgrade

Step 1 of the migration — the version upgrade. It follows Redis's official rolling upgrade: replace old nodes one at a time with new-version replicas, then do a planned failover, with no downtime.

The main flow uses standalone master/replica; Redis Cluster differences are in the supplement at the end.

Reference: Redis official Redis administration · Upgrading without downtime.

Applicability & prerequisites

  • Scenario: Redis 6.x (first align to 6.2.x within the major version) rolling-upgraded to 7.2.x.
  • Prerequisites: replication healthy and planned failover possible; the master has persistence enabled or does not auto-restart on crash (to avoid an empty master wiping replicas).

Before the upgrade

  • Config alignment (old and new consistent): maxmemory and eviction policy, AOF / RDB policy, requirepass / masterauth, connections and timeouts, TLS, replication backlog (sized to memory).
  • Compatibility check (high level): inventory production commands / usage from real command logs (Lua, Streams, blocking commands, Module, etc.); verify high-frequency and high-risk usage. No need to compare full version-diff lists.
  • Backup & baseline: run one BGSAVE; record topology and connection / latency baselines.

Upgrade-friendly configuration (optional)

The main risks during upgrade / adding replicas are a full-resync loop and master pressure spikes. The following help make rolling failover smoother (tune values by data size — do not copy numbers):

Config Purpose
repl-backlog-size Enables partial resync after a disconnect, avoiding a full resync
client-output-buffer-limit replica … Prevents the replica output buffer from overflowing and being dropped under heavy writes + initial sync (which causes a resync loop)
repl-diskless-sync / -delay On slow disks, streams the full sync over the network without hitting disk, easing master disk pressure
repl-timeout Raise for large datasets / slow links to avoid false timeouts triggering resync
maxmemory headroom Memory can reach ~2× during sync / RDB; leave headroom to avoid OOM

Safety prerequisites (not tuning): the master has persistence enabled or does not auto-restart on crash; upgrade replicas via SHUTDOWN (save & quit) for partial resync; promote with REPLICAOF NO ONE — do not enable a writable replica as an intermediary step.

Rationale: Redis official Replication and Administration docs.

Upgrade flow (main: standalone master/replica)

① Add 7.2 replica New 7.2 instance replicates from the old 6.x master; catch up ② Verify Same key count, master_link_status:up, offset aligned ③ (optional) load test ④ Failover Pause writes → wait replica to catch up offset → promote 7.2 → repoint clients ⑤ Soak Keep the old 6.x node (duration up to you); run the checklist ⑥ Wrap up Retire the old 6.x node

Key actions (example commands, adjust per environment)

  • Add replica: on the new 7.2 instance, REPLICAOF <old-master-ip> <port> (set masterauth first if needed); wait for initial sync to finish.
  • Catch-up check: INFO replication shows master_link_status:up, offset aligned with the master, stable lag.
  • Failover (establish a consistency point, then promote):
    1. On the old master, CLIENT PAUSE WRITE <ms> to briefly pause writes (Redis 6.2+).
    2. Record the old master's master_repl_offset from INFO replication.
    3. Wait for the 7.2 replica's offset to reach that value (confirming it processed the stream up to the pause).
    4. REPLICAOF NO ONE on the 7.2 replica to promote it.
    5. Repoint clients to the new master.
    6. Take the old master out of write service; if soaking, decide its fate per the rollback plan.

7.2 can load a 6.x RDB (forward-compatible), so "7.2 replicating from an old 6.x master" works fine.

Redis Cluster supplement

Cluster can reuse the "per-shard add replica, catch up, manual failover" idea, but a separate dry run before production is recommended — do not extrapolate single-instance results to Cluster.

Same core flow; the differences are commands and cutover:

  • Add replica: new 7.2 node CLUSTER MEET to join, then CLUSTER REPLICATE <master-node-id>.
  • Failover: on the target 7.2 replica, CLUSTER FAILOVER, one shard at a time (verify cluster_state:ok, role:master before the next). CLUSTER FAILOVER already pauses the primary, ships the offset, and waits for the replica to catch up before completing, so you don't add a bare CLIENT PAUSE on top; by default do not use FORCE / TAKEOVER. Slots stay with the promoted node.
  • Cutover: Cluster clients follow the topology automatically — no manual repointing.
  • Retirement order: remove the old 6.x replicas first, the old 6.x master last.

Verification checkpoints

Stage Check Pass criteria
Before health / version / replication replication OK (Cluster: cluster_state:ok)
After add replica catch-up master_link_status:up, offset aligned
After failover new master role role:master (Cluster: cluster_state:ok)
Throughout sample consistency sampled Key + Value + TTL match
Soak latency / errors / connections / memory no clear regression, no ERROR logs

Rollback

  • Reversible during the soak: re-promote the original 6.x master and repoint clients (Cluster: CLUSTER FAILOVER back).
  • Two cross-major-version constraints:
    • The old 6.x cannot load a 7.2 RDB, so it cannot stably replicate from 7.2 (any full resync would fail). The kept old node is only a "snapshot at cutover time" — do not restart / rebuild old nodes during the soak.
    • Therefore a rollback loses writes made to 7.2 after cutover. For consistency-sensitive workloads, briefly freeze writes at cutover to minimize the rollback inconsistency window.

Back to Migration overview · Next: Redis 7.2 → Engula.

ON THIS PAGE