As you are probably aware, Redis decided to switch to a source-available, SSPLv1 license. This means, as of Redis 7.4, it is no longer considered “open source.” Because of this change, Valkey launched its fork, retaining the original BSD open source license. At the same time, Percona announced our partnership with Valkey and the Linux Foundation as contributors and community evangelists.

Naturally, the first question that comes to mind is, “How do I migrate from Redis to Valkey?” We are glad you asked!

Note: This post assumes you already have Redis installed, running, and containing some dataset you want to preserve and/or migrate to Valkey.

Install Valkey

Getting Valkey installed is fairly straightforward. If you are a docker user, you can simply docker pull valkey/valkey:7.2.5 and launch a container.

Alternatively, you can find Valkey 7.2.5 available in the Percona repositories for all our supported operating systems. As a quick example, here are the steps for Ubuntu:

The default configuration file is located at /etc/valkey/valkey.conf. Edit the config to suit your needs, and then restart Valkey to take effect. Most notably, you’ll want to set the dir location for the database snapshot, configure save for routine disk persistence, and other best practices.

Migration option: Physical

There are several methods to migrate from Redis to Valkey. The easiest and fastest method is physical, where you can simply copy the most recent on-disk snapshot from the Redis server over to our Valkey server and start Valkey. Valkey will read the snapshot file on startup and restore the contents to memory. In the example below, we take a fresh snapshot of our Redis server to give us the most up-to-date data.

Backup complete. Copy the RDB dump to Valkey’s data directory and start Valkey. Make sure that you copy the backup to the configured path and file in your Valkey configuration.

NOTE: If you enabled AOF in your Valkey configuration, you will need to disable it on the first start; otherwise, the copied RDB file will not be imported into Valkey.

Depending on the size of the backup, it will take Valkey a moment to load the contents into memory.

Migration complete! This process works even if Valkey is on a new server; simply use scp instead to copy the RDB file to the new server.

Note: You could have also simply stopped Redis and started Valkey pointing to the same data directory, effectively doing an in-place swap. However, if, for some reason, the swap fails and you need to shut down Valkey, it will overwrite the RDB file, and data loss will occur. If you decide to go this route, be sure to copy your RDB file somewhere safe for a backup.

Migration option: Replication

The main issue with migrating using a snapshot is that there will be some amount of downtime while you shut down Redis, start Valkey, and wait for Valkey to populate its memory with the copied snapshot. This could take several minutes, depending on how large your snapshot is and how fast the CPU/memory/disk can be.

If downtime is something you want to minimize, we can migrate “online” using replication. Replication is a native function of Redis/Valkey, allowing keys, streams, and other data types to be replayed on another server to create a ‘hot spare’ to handle load distribution and assist with fault tolerance.

Let’s configure our Valkey to become a replica of our Redis master. In our example below, Redis 6.2.14 is running on the default port of 6379. We will configure Valkey on the same host to listen on port 6380. For simplicity, there is no authentication configured, and no SSL/TLS is configured, though both of these are highly recommended best practices in a typical Valkey deployment.

As soon as we execute the ‘REPLICAOF’ command in Valkey, it will connect to the Redis server and begin copying all of the keys. We can watch the status of replication on Valkey:

Now that the two are in sync, we can shut down the old Redis and point our applications to port 6380. You could also stop Valkey and switch back to the default port. Other options for a more “zero downtime” migration might include additional interfaces/IPs on the same host, migrating to a different host, and updating DNS entries.

Be sure to halt Valkey replication by running “REPLICAOF NO ONE” before moving applications, as this stops the data migration and disables read-only mode.

Migration option: Dump ‘n load specific keys

In both migration options presented so far, the entire keyspace is migrated from old Redis to Valkey. However, there may be a situation where you don’t need all of the keys migrated but only a handful of critical keys to move over. There are two ways to accomplish this.

Valkey/Redis has a native serialization function, allowing you to export specific keys in an easy-to-copy string-based representation. You can then restore this key to the new server.

Note: The name of the key, and the key’s remaining TTL are not part of the serialized data and must be specified on RESTORE.

If you have more than one key that you need to restore to the new Valkey server, you might instead opt to use the MIGRATE command. Running this command on the old Redis server will connect to the new Valkey server and will atomically transfer keys and their values to the destination server. Once verified on the destination server, the keys are removed from the original master unless otherwise specified.

In this example, we used the MIGRATE command to copy (i.e., do not remove from source), and replace (i.e., use the old value if the key already exists), the keys ‘mydata’, and ‘coolmsg’ (which we RESTORE‘d earlier), to our Valkey server.

Conclusion

Migrating from Redis to a truly open source Valkey is fairly straightforward. We can migrate our entire dataset by simply copying a database snapshot from old to new. We also learned how to quickly configure replication to duplicate the data from old to new, providing an ‘online’ alternative. Lastly, we saw how to dump and migrate individual keys.

Subscribe
Notify of
guest

5 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
mike

following https://www.percona.com/blog/new-valkey-packages-by-percona/ repo not working on ubuntu 22

 sudo percona-release enable valkey
Specified repository is not supported for current operating system!

Description:  Ubuntu 22.04.4 LTS
Release:    22.04
Codename:    jammy

0
Reply
Matthew Boehm

Hello mike, our repo engineer confirmed a bug in the repo itself. A fix is on the way. Please try again in a couple of hours. Thanks for trying out Valkey!

0
Reply
Alvaro

Hello!, same issue seen on Ubuntu 20.04.5 LTS

root@ulc5:~# percona-release enable valkey release * Enabling the Percona Original repository <*> All done! ==> Please run “apt-get update” to apply changes root@ulc5:~# percona-release show The following repositories are enabled on your system: original – release prel – release valkey – release <*> All done! root@ulc5:~# apt-get install valkey Reading package lists… Done Building dependency tree Reading state information… Done E: Unable to locate package valkey root@ulc5:~# cat /etc/os-release NAME=”Ubuntu” VERSION=”20.04.5 LTS (Focal Fossa)” ID=ubuntu ID_LIKE=debian PRETTY_NAME=”Ubuntu 20.04.5 LTS” VERSION_ID=”20.04″ HOME_URL=”https://www.ubuntu.com/” SUPPORT_URL=”https://help.ubuntu.com/” BUG_REPORT_URL=”https://bugs.launchpad.net/ubuntu/” PRIVACY_POLICY_URL=”https://www.ubuntu.com/legal/terms-and-policies/privacy-policy” VERSION_CODENAME=focal UBUNTU_CODENAME=focal

0
Reply
Greg

Issue here on ubuntu 22.04 with the instructions provided in the post:

$ sudo percona-release enable valkey
* Enabling the Percona Valkey repository
[…]
Hit:13 http://repo.percona.com/valkey/apt jammy InRelease
[…]
=> seems ok

but
$ sudo apt install valkey
Reading package lists… Done
Building dependency tree… Done
Reading state information… Done
E: Unable to locate package valkey

$ apt-cache search valkey
=> doesn’t find anything…

0
Reply
Greg

one way to make it work is use
$ sudo percona-release enable valkey testing

It currently provides “valkey/stable 1:8.0.0-1.jammy amd64″

0
Reply