Migrating from Redis to Valkey can significantly reduce costs associated with private licensing for your application. However, the biggest concern in any migration is transitioning without disrupting service or causing downtime. In this blog post, we’ll guide you through a step-by-step approach to smoothly migrate from Redis to Valkey without interrupting your application’s operations, providing the best practices to ensure a seamless switch while keeping your systems running.

We will work with a three-node replica set with auto-failover using redis-server and redis-sentinel and their Valkey alternatives running on Docker. We will migrate using the same version, 7.2. Here is a compatibility matrix from Valkey’s official documentation.

Migration compatibility matrix

You can migrate a Redis server to Valkey. The following table provides migration options depending on the Redis version you run:

Redis  Valkey
6.x       7.2.x
7.2.x    7.2.x
7.2.x    8.0.x
7.4       n/a

We will use port 600X for our data nodes and 2600X for our sentinel nodes. Check those ports are available before running the snippet, and change them if they are already used on your system.

The next command should return empty if the ports are available.

To quickly create a test environment, run this snippet to create directories, configuration files, and ACL files and run the containers with all the required parameters.

Our data, config, and logs directory for each node are created as follows.

The snippet.

Once you run the snippet, you should have the following containers running.

Once we have our cluster ready, we will insert 10K keys with random values.

Now that we created all the SET statements we can execute them in bulk using the --pipe option.

We can check the number of keys with the INFO keyspace command.

The migration process involves migrating one node at a time. We will start by migrating the sentinel nodes. After every container is migrated, it is a good practice to check the logs and status of the node to be able to roll back in case anything goes wrong.

You can also wait a day or more before proceeding to the next node to ensure everything works properly.

We will reuse the same configuration, log, and ACL files and directories.

The changes we are making are the container name prefix from redis to valkey, the container image from redis:7.2 to valkey/valkey:7.2, and the command run by the container to match the proper binary. We will highlight the differences in bold text for the first command, and all following commands will have the exact differences.

Let’s begin by migrating the first redis-sentinel container.

You can tail the log file and use the INFO command to check the status.

We can also check the node with the INFO server sentinel command.

Then, we need to do the same for all other sentinels.

redis-sentinel-1

redis-sentinel-0

Once all our sentinel nodes are running Valkey, we can continue migrating the redis-server nodes, starting with the replicas, to avoid downtime.

You can run this command to identify the current replicas.

We will start with node redis-2.

Always check the logs, server, and replication information to ensure everything works.

When we stop a Redis/Valkey data node, the shutdown process saves the node’s state into an RDB file. This allows the server to recover from the disk when starting up again, so the node doesn’t need to do a full sync, which can take time in a big production deployment.

If you have a write-heavy cluster or you have one replica down for a long time, you might want to tune the repl-backlog-size configuration parameter.

The backlog serves as a buffer that holds replica data during periods of disconnection. This enables replicas to catch up with a partial resync, receiving only the data they missed rather than requiring a full resync.

Let’s analyze the log to understand the process better.

We can also run the INFO command to check the version, status, and number of keys.

We will do the same for node redis-1, the other replica.

Remember to check the logs and output of the INFO  command.

The last step is to migrate the current master. First, we need to trigger a manual switchover so that the current master becomes a slave.

Connect to a sentinel node, authenticate, and run the SENTINEL FAILOVER  command. Then, run the SENTINEL GET-MASTER-ADDR-BY-NAME  command to ensure that a new master gets elected.

Now, we can exit and migrate node redis-0.

Again, check the logs and INFO  for the new node to ensure everything works properly.

As we haven’t deleted the redis-server and redis-sentinel nodes, it is pretty simple to do a rollback by just stopping the Valkey containers and starting the Redis ones. In case this is needed, do it in a rolling way, starting with the replicas.

Please refer to this documentation for more information about migrating from Redis to Valkey or learn more about our support for the Valkey project and its community.

Subscribe
Notify of
guest

2 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Christian ROUX

Thanks for that very interesting post.
I tested a migration from Redis 6.2.14 to Valkey 8.0.1 without any issue.
Do you confirm that ?

1
Reply
Agustin Palazuelos

Thanks for letting us know. Valkey 8 wasn’t released when I created this post and upgrading several major versions is not fully tested yet. It’s great to know it worked for you.
Stay tuned for future Valkey posts.
Cheers!

0
Reply