Plan a Safe Redis-to-Valkey Migration

Migrating from Redis to Valkey requires more than replacing a package. You need a compatible source version, a recoverable data copy, the application’s credentials and permissions, and a cutover that does not lose writes. This guide describes a maintenance-window migration for a standalone instance; it is not a cluster or Sentinel failover procedure.

Confirm compatibility before changing packages

Valkey’s official migration guide covers Redis OSS 7.2 and earlier. Redis 7.4 and later data files are not interchangeable with that path. Modules, client assumptions, authentication, persistence and deployment packaging still need individual checks. Do not infer compatibility solely from port 6379 or the presence of redis-cli.

Record the exact Redis version, package source, client libraries, enabled modules, logical databases, persistence settings and deployment type. On a local instance using password authentication, these read-only commands provide a starting inventory:

redis-cli --user default --askpass INFO server
redis-cli --user default --askpass INFO keyspace
redis-cli --user default --askpass INFO persistence

Use an authorized administrative account, not necessarily default. Add your actual host, port and required TLS/certificate options for a remote connection. Do not put passwords into command-line arguments or publish unredacted configuration output. Key counts cover presence, not complete application correctness.

Prepare a separate staging target

Before uninstalling Redis, build an isolated Valkey target using the supported installation method for your operating system. Keep it inaccessible to normal application clients. Use a distinct data directory and endpoint; never let both processes write to the same data files.

Review the target’s bind addresses, protected mode, TLS, users, ACLs and file ownership. Copy required ACL and included configuration files deliberately. A text substitution from redis to valkey is not a safe general configuration converter: it can change passwords, application values and paths that should remain unchanged.

Distribution compatibility packages can replace commands or services and run installation hooks. Inspect the exact package behavior in staging before using one on a production host. Do not assume it preserves every auxiliary file or that installing a package cannot start a service.

Create and verify a recoverable copy

Keep a private backup of the original configuration, ACLs, required certificates and persistence files. Protect secrets and retain an off-server copy according to your recovery policy. Identify the actual data directory rather than assuming a distribution default.

Rehearse a restore into the isolated target. For an RDB-based transfer, use a completed snapshot generated by a compatible source. AOF-enabled instances can use multipart files and a manifest; do not copy only one file or place an unrelated AOF beside the transferred RDB and assume the intended dataset will load. Follow the persistence-specific method for the exact versions.

A file checksum confirms that a transfer retained the bytes, not that the database can load them. Start the isolated target, inspect its startup log and query representative data before treating the backup as usable.

Freeze writes before the final snapshot

Schedule the outage with application owners. Stop or otherwise prevent every writer, including workers, cron jobs and integration clients. Disconnecting only a web frontend is insufficient when background jobs can still change data.

After writers are quiesced, an authorized administrator can make the final synchronous snapshot:

redis-cli --user default --askpass SAVE

SAVE blocks the server while it runs; its duration depends on the dataset. Require success and keep writes stopped through the transfer and cutover. Taking a snapshot and then allowing more writes creates a gap that the snapshot cannot cover. If the application cannot tolerate this window, use a separately tested replication-based migration instead of this procedure.

Stop the source through its actual service/container manager after preserving the final consistent state. Transfer a private copy to the target prepared during rehearsal, using the ownership and persistence layout verified there. Keep the original files unchanged for recovery.

Validate before releasing application traffic

Start Valkey on its isolated endpoint and inspect its server identity, persistence status and keyspace. Use your actual connection parameters:

valkey-cli --user default --askpass INFO server
valkey-cli --user default --askpass INFO keyspace
valkey-cli --user default --askpass INFO persistence

Check all logical databases used by the application, representative value types, expected TTL behavior and required modules. Expiring keys can legitimately change counts, so compare timestamps and semantics rather than demanding an unexplained exact count.

Test with the application’s restricted user as well as the administrator. Confirm allowed operations succeed and forbidden keys/commands remain denied. Run a disposable application transaction, inspect reconnect behavior, and verify persistence across a controlled target restart. Do not use customer records as disposable test data.

Only after those checks should you update the client endpoint or switch the service according to the rehearsed plan. Release writers deliberately and monitor application errors, latency and data changes. Existing client protocol compatibility does not guarantee that every application assumption is valid.

Define rollback before accepting new writes

Before cutover, document the acceptance tests, decision owner and point after which rollback requires data reconciliation. Restarting Redis from the original backup restores the pre-cutover state, not writes later accepted by Valkey. Do not overwrite the source directory while a package installation may have restarted its service.

If the target has accepted writes, stop writers and preserve that target state before deciding how to recover. Newer persistence formats may not be readable by an older Redis release. Rehearse the reverse path or use an application-level reconciliation plan; a package downgrade is not a data-recovery strategy.

Keep backups until the documented retention period and recovery acceptance criteria have been met. There is no universal safe instruction to delete them after one week.