Update the redis to valkey migration guide - migration.md #247

milliehartnt123 · 2025-03-11T19:53:25Z

Suggested updates to the migration guide, based on running through the migration steps and finding additional information that is useful for the user. Changes include rewording some of the text, and restructuring. A few additional steps were also introduced to assist new users.

Suggested updates to the migration guide, based on running through the migration steps and finding additional information that is useful for the user. Changes include rewording some of the text, and restructuring. A few additional steps were also introduced to assist new users. Signed-off-by: milliehartnt123 <[email protected]>

milliehartnt123 · 2025-03-11T20:11:27Z

@madolson and @zuiderkwast please review my changes to the migration guide.

ranshid · 2025-03-27T11:31:53Z

topics/migration.md


-   a. Connect to Redis and check the number of keys:
+2. In your Redis container, connect to `redis-cli` and check the number of keys, using the `INFO KEYSPACE` command. This will be used later to verify that the entire database has been successfully migrated. In this example, `keys=6286` indicates that there are 6.286 keys in the database.


Suggested change

2. In your Redis container, connect to `redis-cli` and check the number of keys, using the `INFO KEYSPACE` command. This will be used later to verify that the entire database has been successfully migrated. In this example, `keys=6286` indicates that there are 6.286 keys in the database.

2. In your Redis container, connect to `redis-cli` and check the number of keys, using the `INFO KEYSPACE` command. This will be used later to verify that the entire database has been successfully migrated. In this example, `keys=6286` indicates that there are 6,286 keys in the database.

"Connect to redis-cli" is not right. redis-cli is a program that you run.

How about "Connect using redis-cli"?

I made the change for 6,286. I also rewrote the "connection" sentence to the following: " Connect to your Redis container using redis-cli, and check the number of keys, using the INFO KEYSPACE command."

ranshid · 2025-03-27T11:52:09Z

topics/migration.md

@@ -21,7 +22,7 @@ You can migrate a Redis server to Valkey.
 Valkey is compatible with Redis OSS 7.2 and all earlier open source Redis versions.
 Migrating from any open source Redis version to Valkey is effectively an upgrade.
 Redis Community Edition (CE), versions 7.4 and later, are not open source and the data files are not compatible with Valkey.
-It may be possible to migrate the data to Valkey from proprietary Redis versions and other Redis-like software but it requires another method and is not covered by this document.
+It may be possible to migrate the data to Valkey from proprietary Redis versions and other Redis-like software, but it requires another method and is not covered by this document.


I wonder why we offer disconnecting as the only suggested method? for example SHUTDOWN save can also produce snapshot which has no extra writes and also using CLIENT PAUSE can help prevent writes while we take a snapshot...

From other comments, they just want to keep this simple. Which is why I removed the BGSAVE steps and just kept using the SAVE command. I did add the comma.

ranshid · 2025-03-27T11:59:26Z

topics/migration.md

+    3) "dbfilename"
+    4) "dump.rdb"
+    ```
+4. Create the backup file. You can either use the `redis-cli` [SAVE](https://redis.io/docs/latest/commands/save/) command or the [BGSAVE](https://redis.io/docs/latest/commands/bgsave/) command to create the backup file. The `SAVE` command performs a synchronous save, blocking all the other clients. However, the `BGSAVE` does the save in the background, forking a child to save the DB, allowing the parent to continue serving the clients. 


I think in the way this manual is currently written there are no clients connected that can be "served" during the save. I think it is fine to keep this part as simple and clean as possible, for example by replacing the use of BGSAVE with SAVE

I removed the BGSAVE and just kept the SAVE.

ranshid · 2025-03-27T12:01:37Z

topics/migration.md


-   For Docker deployments, copy the RDB file to your host and start a Valkey container mounting this file to the container's data directory. Replace the `<container-name>` and `<path/on/host>` placeholders with your values.
+	- Redis container mounted to host directory: 


Suggested change

- Redis container mounted to host directory:

- In case both Redis and Valkey containers are mounted to host directory:

Made the change.

Changed it to, "If the Redis and Valkey containers are both mounted to a host directory: "

ranshid · 2025-03-27T12:02:01Z

topics/migration.md

+        Copy the RDB file from the host directory mounted to the Redis container to the host directory being mounted to the Valkey container.
+
+
+	- Redis container not mounted to host directory:


Suggested change

- Redis container not mounted to host directory:

- In case both Redis and Valkey containers are not mounted to host directory:

So the example as shown, uses docker cp to copy the saved backup file out of the Redis container to the host directory that will be mounted to the Valkey container /data directory. If you want both Redis and Valkey to not be mounted to a host directory, then the example needs another docker cp to copy it from some host directory to the /data directory of the Valkey container. But I tried that, and I couldn't get it to work,

ranshid · 2025-03-27T12:09:49Z

topics/migration.md

   ```
-
-   Start Valkey:
+   In this example, the container is named, `somevalkey` and the image name is `valkey/valkey`. It is mounting whatever is set as the directory path on the host to the Docker container `/data` directory.    


I think it is strange that we provide a command to run (line 136) and provide an incomplete example (with <path/on/host>) I think just keeping the command in line 136 is good enough

Removed partial example.

ranshid · 2025-03-27T12:44:36Z

topics/migration.md

    master_sync_in_progress:0
    ....
    ```

-4. Now that the two are in sync, check that your applications connect to Valkey and shut down your Redis instance. 
+5. Once Redis and Valkey are synchronized, verify that your applications connect to Valkey and shut down your Redis instance. 


Note that since Redis 7.0 the shutdown will also wait fior the replicas to sync on shutdown. this can also be controlled with the shutdown-timeout configuration. I suggest maybe we add this and a note about potential data loss in case there are writes active on the redis primary while we are syncing.

ranshid · 2025-03-27T12:50:01Z

topics/migration.md

-     * `KEYS`. Specify the key(s) to migrate
-
-     For example, to migrate the `message` and `mydata` keys to the Valkey instance with the IP address 172.21.0.3, the command looks as follows:
+3. Start the `valkey-cli` in your Valkey container and get the database number using the `INFO KEYSPACE` command. In this example, the database number is `0` (db0).


Not sure if this is needed. when user is using multiple databases he should be aware of the db he is migrating the key from and decide on the destination database he is migrating to. if we would like to extend the directives in this case we should probably add the use of select before migrate each of the keys to be migrated. in most migration cases we would like to preserve the database so just a simple select and use the same database as the target would be enough IMO.

zuiderkwast

I didn't review the actual content much. I mainly commented on formatting and coding style.

@nastena1606 you're the original author of this document. Do you want to take a look?

zuiderkwast · 2025-03-27T13:15:15Z

topics/migration.md


-   a. Connect to Redis and check the number of keys:
+2. In your Redis container, connect to `redis-cli` and check the number of keys, using the `INFO KEYSPACE` command. This will be used later to verify that the entire database has been successfully migrated. In this example, `keys=6286` indicates that there are 6.286 keys in the database.


"Connect to redis-cli" is not right. redis-cli is a program that you run.

How about "Connect using redis-cli"?

zuiderkwast · 2025-03-27T13:15:53Z

topics/migration.md

-   c. Check the timestamp of the last save operation
+3. Check the configuration for the directory (`dir`) where Redis stores its database files and the name of the database file (`dbfilename`). In this example, Redis saves the backup into the `/data/dump.rdb` file
+
+	> NOTE: If your Redis Docker container `/data` directory is mounted to a directory on your host, the RDB file is also written to that host directory.


Please use spaces, not tabs.

There are many tabs in this change, not only on this line.

zuiderkwast · 2025-03-27T13:20:30Z

topics/migration.md

+
+	- Using `BGSAVE`
+
+		a.  Check the timestamp of the last save operation, using the [LASTSAVE](https://redis.io/docs/latest/commands/lastsave/) comamnd.


Link to commands using relative links to the md file as in this repo, like [LASTSAVE](../commands/lastsave.md).

These docs are not only used for the website. They are also used for man pages.

Relative links like these also work when you click on them in the github web view.

zuiderkwast · 2025-03-27T13:22:21Z

topics/migration.md

+      ```
+		redis 127.0.0.1:6379> SAVE
+		OK
+      ```


There is excessive indentation here. The example should be indented the same as the triple backticks. Otherwise, a lot of spaces will be part of the example which is not what the CLI looks like.

zuiderkwast · 2025-03-27T13:24:16Z

topics/migration.md

-   # Keyspace
-   db0:keys=6286,expires=0,avg_ttl=0
-   ```
+      ```


Please revert these unnecessary changes to spaces.

zuiderkwast · 2025-03-27T13:31:00Z

topics/migration.md

+
+4. From the Redis server, run the `MIGRATE` command:
+     ```
+     MIGRATE <Valkey_IP> <Valkey_port> <key | ""> <Valkey-db-number> <timeout> [COPY] [REPLACE] [AUTH password | AUTH2 username password] [KEYS key [key ...]]


This is a mix of different ways to write syntax. Some placeholders use <name> and some just name.

In general, we don't use <name> for placeholders. We just write them as name in lowercase and we write fixed strings in uppercase.

We do use < and > for grouping meaning one of multiple alternatives, for example <key | ""> meaning either a key or "".

Preferred style:

MIGRATE valkey-ip valkey-port <key | ""> valkey-db-number timeout [COPY] ...

zuiderkwast · 2025-03-27T13:33:34Z

topics/migration.md


    ```
-    $ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' valkey-1
+    $ docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' valkey-1    


Don't add this trailing whitespace

zuiderkwast · 2025-03-27T13:33:51Z

topics/migration.md


    ``` 
    $ docker exec -it <redis-1> bash
    $ redis-cli --cluster add-node <valkey-node-IP>:6379 <existing-node-IP>:6379 --cluster-replica
    ```

-6. Check the cluster status
+6. Check the cluster status. The output of the cluster nodes command is described in [CLUSTER NODES](https://redis.io/docs/latest/commands/cluster-nodes/).


Suggested change

6. Check the cluster status. The output of the cluster nodes command is described in [CLUSTER NODES](https://redis.io/docs/latest/commands/cluster-nodes/).

6. Check the cluster status. The output of the cluster nodes command is described in [CLUSTER NODES](../commands/cluster-nodes.md).

zuiderkwast · 2025-03-27T13:34:25Z

topics/migration.md


-8. Promote it to be a new primary. Run the following command **from the node you wish to promote**:
+8. Start the `valkey-cli` in your new Valkey container and enter the following command to promote it to be primary. [Cluster Failover](https://valkey.io/commands/cluster-failover/) provides additional information.


Suggested change

8. Start the `valkey-cli` in your new Valkey container and enter the following command to promote it to be primary. [Cluster Failover](https://valkey.io/commands/cluster-failover/) provides additional information.

8. Start the `valkey-cli` in your new Valkey container and enter the following command to promote it to be primary. [CLUSTER FAILOVER](../commands/cluster-failover.md) provides additional information.

zuiderkwast · 2025-03-27T13:34:50Z

topics/migration.md

   valkey 127.0.0.1:6379> cluster failover
   OK
   ```

-9. Check the cluster state. You should now see the previous replica to be a new primary.
+9. Use the `cluster nodes` command to display the cluster state and verify that your new Valkey node is now a new primary.


Write commands in uppercase.

Suggested change

9. Use the `cluster nodes` command to display the cluster state and verify that your new Valkey node is now a new primary.

9. Use the `CLUSTER NODES` command to display the cluster state and verify that your new Valkey node is now a new primary.

ranshid reviewed Mar 27, 2025

View reviewed changes

zuiderkwast requested a review from nastena1606 March 27, 2025 13:10

zuiderkwast reviewed Mar 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the redis to valkey migration guide - migration.md #247

Update the redis to valkey migration guide - migration.md #247

milliehartnt123 commented Mar 11, 2025

milliehartnt123 commented Mar 11, 2025

ranshid Mar 27, 2025

zuiderkwast Mar 27, 2025

milliehartnt123 Mar 28, 2025

ranshid Mar 27, 2025

milliehartnt123 Mar 28, 2025

ranshid Mar 27, 2025

milliehartnt123 Mar 28, 2025

ranshid Mar 27, 2025

milliehartnt123 Mar 28, 2025

milliehartnt123 Mar 28, 2025

ranshid Mar 27, 2025

milliehartnt123 Mar 27, 2025

ranshid Mar 27, 2025

milliehartnt123 Mar 28, 2025

ranshid Mar 27, 2025

ranshid Mar 27, 2025

zuiderkwast left a comment

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025

zuiderkwast Mar 27, 2025


		a. Connect to Redis and check the number of keys:
		2. In your Redis container, connect to `redis-cli` and check the number of keys, using the `INFO KEYSPACE` command. This will be used later to verify that the entire database has been successfully migrated. In this example, `keys=6286` indicates that there are 6.286 keys in the database.


		For Docker deployments, copy the RDB file to your host and start a Valkey container mounting this file to the container's data directory. Replace the `<container-name>` and `<path/on/host>` placeholders with your values.
		- Redis container mounted to host directory:

	- Redis container mounted to host directory:
	- In case both Redis and Valkey containers are mounted to host directory:

		Copy the RDB file from the host directory mounted to the Redis container to the host directory being mounted to the Valkey container.


		- Redis container not mounted to host directory:


		- Using `BGSAVE`

		a. Check the timestamp of the last save operation, using the [LASTSAVE](https://redis.io/docs/latest/commands/lastsave/) comamnd.

	6. Check the cluster status. The output of the cluster nodes command is described in [CLUSTER NODES](https://redis.io/docs/latest/commands/cluster-nodes/).
	6. Check the cluster status. The output of the cluster nodes command is described in [CLUSTER NODES](../commands/cluster-nodes.md).


		8. Promote it to be a new primary. Run the following command from the node you wish to promote:
		8. Start the `valkey-cli` in your new Valkey container and enter the following command to promote it to be primary. [Cluster Failover](https://valkey.io/commands/cluster-failover/) provides additional information.

	9. Use the `cluster nodes` command to display the cluster state and verify that your new Valkey node is now a new primary.
	9. Use the `CLUSTER NODES` command to display the cluster state and verify that your new Valkey node is now a new primary.

Update the redis to valkey migration guide - migration.md #247

Are you sure you want to change the base?

Update the redis to valkey migration guide - migration.md #247

Conversation

milliehartnt123 commented Mar 11, 2025

milliehartnt123 commented Mar 11, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zuiderkwast left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment