rabbitmq-upgrade

Wait for all quorum queues to have an above minimum online quorum

$ rabbitmq-upgrade await_online_quorum_plus_one

$ rabbitmq-upgrade drain

$ rabbitmq-upgrade revive

$ rabbitmq-upgrade post_upgrade

$ rabbitmq-upgrade help

rabbitmq-upgrade command [options]

status
    Checks the current upgrade status of the node, reporting if an upgrade is in progress, pending, or complete.

drain
    Stops all RabbitMQ applications on the node, but keeps the Erlang VM running. This is a preparatory step for upgrades, allowing the node to gracefully stop processing messages without fully shutting down.

perform_upgrade
    Executes the actual upgrade process. This command performs data migrations, converts necessary files, and prepares the node for the new RabbitMQ version. It should be run after `drain` and installing the new RabbitMQ package.

cleanup_reboot
    Performs cleanup tasks after an upgrade, which might include removing old data files or finalizing the upgrade state. It's often used if `perform_upgrade` didn't complete a full cleanup or after a system reboot.

forget_upgrade
    Resets the node's upgrade state, effectively telling RabbitMQ to forget about any pending or failed upgrade attempts. Use with caution, typically when reverting to an older version or retrying a failed upgrade.

list_unsupported_versions
    Lists all nodes in a cluster that are running versions incompatible with a direct upgrade path to the target version, helping to identify potential issues in multi-node environments.

--timeout seconds
    Sets a timeout for the upgrade operation in seconds. If the operation exceeds this time, it will be aborted.

--description text
    Adds a user-defined description to the upgrade event, which can be useful for logging and tracking upgrade history.

The rabbitmq-upgrade command facilitates the process of upgrading a RabbitMQ server node, particularly when moving between major or minor versions that require data format changes or other significant migrations. It's designed to manage the delicate state transitions during an upgrade, ensuring data consistency and minimizing manual intervention. The command typically stops RabbitMQ applications, performs necessary data conversions or schema migrations, and then restarts the applications.

It's a critical component of the RabbitMQ upgrade toolkit, intended to be run after a new version of RabbitMQ is installed but before the server is fully started. While `rabbitmq-upgrade` automates many steps, users must always consult the official RabbitMQ upgrade guide for their specific version path, as preparatory steps, Erlang/OTP compatibility, and cluster upgrade strategies are crucial and often vary.

Always backup your RabbitMQ data directory before attempting any upgrade.
Consult the official RabbitMQ upgrade guide for your specific version path; instructions often vary significantly between major versions (e.g., 3.x to 4.x).
Ensure Erlang/OTP version compatibility with the new RabbitMQ version.
Cluster upgrades require careful planning; refer to the documentation for rolling upgrade strategies.
Downtime is typically required for a single-node upgrade and often for cluster upgrades as well.
Monitor system resources (disk space, memory) during the upgrade process.

A common single-node upgrade sequence involves these high-level steps:
1. Stop the existing RabbitMQ service.
2. Install the new RabbitMQ package.
3. Run `rabbitmq-upgrade drain`.
4. Run `rabbitmq-upgrade perform_upgrade`.
5. Start the new RabbitMQ service.
6. (Optional) Run `rabbitmq-upgrade cleanup_reboot` if needed.
Always verify these steps with the official guide for your specific version.

Upgrading a RabbitMQ cluster requires a more coordinated approach. It typically involves either a full cluster shutdown and upgrade, or a rolling upgrade where nodes are upgraded one by one, minimizing total downtime. The `list_unsupported_versions` command is particularly useful for planning cluster upgrades and identifying potential roadblocks before starting the process.

The `rabbitmq-upgrade` command has been an integral part of the RabbitMQ ecosystem for managing version transitions. Its functionality has evolved with RabbitMQ itself, becoming more robust to handle complex data migrations and ensure compatibility across significant architectural changes, such as those introduced in RabbitMQ 3.x and 4.x series. It centralizes the upgrade logic, reducing the need for manual file manipulations and intricate step-by-step procedures that were more common in very early versions.

rabbitmqctl(1), rabbitmq-plugins(1), rabbitmq-diagnostics(1)