By using the hot upgrade feature, users can quickly and safely upgrade the EMQ X Broker in the production environment, and avoid the decrease in system availability caused by restarting the service.

Currently EMQ X Broker only supports hot upgrade of Patch version (Patch version is the third digit of the version number). That is, it currently supports hot upgrades from 4.2.0 -> 4.2.1, 4.2.0 -> 4.2.2, …, etc., but 4.2.x cannot be hot upgraded to 4.3.0 or 5.0.

Currently, EMQ X for Windows does not support hot upgrade feature.

  1. View the currently installed version list of EMQ X Broker.
  1. Download the software package to be upgraded from the EMQ X website.
  1. Find the installation directory of EMQ X:
  2. $ EMQX_ROOT_DIR=$(emqx root_dir)
  4. $ echo ${EMQX_ROOT_DIR}
  5. "/usr/lib/emqx"
  1. Put the downloaded zip package in the releases directory under the EMQ X installation directory:
  1. $ cp emqx-4.2.1.zip ${EMQX_ROOT_DIR}/releases/
  1. Upgrade to the specified version:
  1. Check the version list again, and the status of the previous version will become old:
  2. $ emqx versions
  4. Installed versions:
  6. * 4.2.0    old

The above emqx upgrade 4.2.1 command actually performs three actions:

  • unpack
  • install
  • permanent

After permanent, this version upgrade will be fixed, which means that after the hot upgrade, if emqx restarts, the new version after the upgrade will be used.

If you don’t want to persist while upgrading, you can use the --no-permanent parameter:

  3. Release 4.2.1 not found, attempting to unpack releases/emqx-4.2.1.tar.gz
  4. Unpacked successfully: "4.2.1"
  5. Installed Release: 4.2.1

After the system has been running stably for a period of time, if you decide to make the new version permant, you can execute the install command again:

  2. $ emqx install 4.2.1
  4. Release 4.2.1 is already installed and current, making permanent.
  5. Made release permanent: "4.2.1"

If you find a problem and want to roll back after the upgrade, you can execute the version downgrade command. For example, the following example will roll back emqx to version 4.2.0:

  2. $ emqx downgrade 4.2.0
  4. Release 4.2.0 is marked old, switching to it.
  5. Made release permanent: "4.2.0"

After the system has been running stably for a period of time, if you decide to delete an old version, you can execute the version uninstall command. For example, the following example will uninstall the old version 4.2.0: