Hot Upgrade
EMQX support hot upgrade since version 4.2.0.
With the hot upgrade feature, users can quickly and safely upgrade the running EMQX in production environment while keeping all the clients connected, ensure high availability because there is no need to restart the service.
TIP
Currently EMQX for Windows and MacOSX does not support hot upgrade feature.
NOTE
EMQX only allows hot upgrade between patch versions (the third digit of the version number). i.e. upgrading from x.y.z to x.y.(z+N) is allowed, but upgrading from x.y to (x+N).(y+M) is not allowed. Please operate with caution.
NOTE
Hot upgrade between EMQX (opensource) and EMQX Enterprise is not allowed, please operate with caution.
Download the Hot Upgrade Zip Package
Go to EMQX Enterprise for the version and the OS you want, and then select the "zip" in the "Install Method".
The Zip package name format of EMQX Enterprise version 4.4 is:
emqx-[EMQX Type]-[EMQX Version]-[OTP Version]-[OS Type]-[Arch].zip
NOTE
EMQX only allows hot upgrade between patch versions (the third digit of the version number). i.e. upgrading from x.y.z to x.y.(z+N) is allowed, but upgrading from x.y to (x+N).(y+M) is not allowed. Please operate with caution.
NOTE
Hot upgrade between EMQX (opensource) and EMQX Enterprise is not allowed, please operate with caution.
Setups for Hot Upgrade
- View the list of currently installed EMQX versions
$ emqx versions
Installed versions:
* 4.4.0 permanent
Check whether the downloaded package type is the same as the currently installed one. Please see the "Download the Hot Upgrade Zip Package" section above.
Locate the EMQX installation directory:
$ EMQX_ROOT_DIR=$(emqx root_dir)
$ echo ${EMQX_ROOT_DIR}
"/usr/lib/emqx"
- Place the downloaded zip package in the
releases
directory under the EMQX installation directory:
$ cp emqx-*4.4.16-*.zip ${EMQX_ROOT_DIR}/releases/
- Upgrade to the specified version:
$ emqx upgrade 4.4.16
Release 4.4.16 not found, attempting to unpack releases/emqx-4.4.16.tar.gz
Unpacked successfully: "4.4.16"
Installed Release: 4.4.16
Made release permanent: "4.4.16"
- View the version list again, and the status of the previous version will change to
old
:
$ emqx versions
Installed versions:
* 4.4.16 permanent
* 4.4.0 old
NOTE
Don't remove any files or directories under the ${EMQX_ROOT_DIR}/releases/
. If you want to remove the specified version, use the emqx uninstall
command.
Permanent the Version Manually after Upgrading
The emqx upgrade 4.4.16
command above actually performs three actions:
- Uncompress the Zip package (
unpack
) - Install it (
install
) - Permanent it (
permanent
)
After persistence, if EMQX restarts, the new version will be used. If you do not want to persist while upgrading, you can use the --no-permanent
parameter:
$ emqx upgrade --no-permanent 4.4.16
Release 4.4.16 not found, attempting to unpack releases/emqx-4.4.16.tar.gz
Unpacked successfully: "4.4.16"
Installed Release: 4.4.16
Now the version has been successfully upgraded to 4.4.16, but it will revert to 4.4.0 after the restart. Now if you lookup the versions, you will find that the status of 4.4.16 is "current", not the persistent version:
$ emqx versions
Installed versions:
* 4.4.16 current
* 4.4.0 permanent
After the system has been running stably for a period of time, if you decide to persist the new version, you can run the install
command again:
$ emqx install 4.4.16
Release 4.4.16 is already installed and current, making permanent.
Made release permanent: "4.4.16"
Downgrade to a Version
If you find a problem after upgrading and want to go back, you can run the version downgrade command. For example, the following example will roll back EMQX to version 4.4.0:
$ emqx downgrade 4.4.0
Release 4.4.0 is marked old, switching to it.
Installed Release: 4.4.0
Made release permanent: "4.4.0"
NOTE
Due to EMQX being backward compatible rather than forward compatible, only immediate downgrade after completing an upgrade is considered safe to ensure no data modifications occurred before the downgrade. If you modify any data through the dashboard, API, or CLI after the upgrade, the behavior of the downgraded system is unknown.
Our recommendation is to only perform version upgrades and never version downgrades. If you encounter any issues after an upgrade, do not downgrade; instead, seek advice from the community or contact our technical support.
Uninstall a Version
If you decide to delete an old version after the system has been running stably for a period of time, you can do the version uninstallation. For example, the following example will uninstall the old version of 4.4.0:
$ emqx uninstall 4.4.0
Release 4.4.0 is marked old, uninstalling it.
Uninstalled Release: 4.4.0