Switch MQ Type for Milvus Standalone

This topic describes how to switch the message queue (MQ) type for an existing Milvus standalone deployment. Milvus supports online MQ switching without downtime.

Prerequisites

• A running Milvus Standalone instance installed via Docker or Docker Compose.
• The Milvus instance has been upgraded to the latest version that supports this Switch MQ feature.

General workflow

The general workflow for switching the MQ type is as follows:

1. Ensure the Milvus instance is running properly.
2. Confirm the source MQ type and the target MQ type.
3. Configure the target MQ’s access settings into the Milvus configuration without changing the mqType value.
4. Trigger the switch by calling the WAL alter API.
5. Monitor the logs to verify the switch has completed successfully.

Switch from RocksMQ to Woodpecker (Local Storage)

This procedure applies to Milvus Standalone Docker deployments that use RocksMQ by default.

Step 1: Verify the Milvus instance is running

Ensure your Milvus Standalone Docker instance is running properly. You can verify this by creating a test collection, inserting data, and running a query.

Step 2: Configure Woodpecker with local storage

Update the Milvus configuration to add Woodpecker settings without changing the mqType value. Create or update the user.yaml file with the following content:

woodpecker:
  storage:
    type: local

Then restart the Milvus instance to apply the configuration:

bash standalone_embed.sh restart

Step 3: Execute the MQ switch

Run the following command to trigger the switch to Woodpecker:

curl -X POST http://<mixcoord_addr>:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

Step 4: Verify the switch is complete

The switch process completes automatically. Monitor the Milvus logs for the following key messages to confirm the switch has finished:

WAL switch success: <MQ1> switch to <MQ2> finish, re-opening required
AlterWAL broadcast message acknowledged by all vchannels
successfully updated mq.type configuration in etcd

Switch from RocksMQ to Woodpecker (MinIO Storage)

This procedure applies to Milvus Standalone Docker Compose deployments.

Step 1: Verify the Milvus instance is running

Ensure your Milvus Standalone Docker Compose instance is running properly.

Step 2: (Optional) Verify Woodpecker configuration

The default Milvus configuration already sets Woodpecker storage type to MinIO, so no additional configuration is required in most cases.

However, if you have previously customized the Woodpecker configuration, you must ensure that woodpecker.storage.type is set to minio. Create or update the user.yaml file with the following content:

woodpecker:
  storage:
    type: minio

Then restart the Milvus instance to apply the configuration:

docker compose down
docker compose up -d

Step 3: Execute the MQ switch

Run the following command to trigger the switch to Woodpecker:

curl -X POST http://<mixcoord_addr>:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

Step 4: Verify the switch is complete

The switch process completes automatically. Monitor the Milvus logs for the following key messages to confirm the switch has finished:

WAL switch success: <MQ1> switch to <MQ2> finish, re-opening required
AlterWAL broadcast message acknowledged by all vchannels
successfully updated mq.type configuration in etcd