HiveMQ Upgrade Guides

HiveMQ Upgrade Guides show you how to upgrade from one HiveMQ version to another HiveMQ version.
For detailed information on HiveMQ installation, configuration, and features, see the HiveMQ User Guide.

HiveMQ Versioning

HiveMQ uses semantic versioning for its version numbers.

Every HiveMQ version uses the following scheme:

major.minor.patch
Each monthly release is compatible with the next 18 monthly releases which automatically includes the next LTS (long-term support) release. For more information, see HiveMQ Rolling Upgrade Policy and our Introducing Flexible MQTT Platform Upgrades with HiveMQ blog post.
Major

Major versions are significant feature releases that add functionality that is not downward compatible with previous versions. Major versions require manual upgrade steps. Customers with professional support may be provided with tools for smooth migration. Major versions can change the extension framework and customers may need to upgrade previously existing extensions to new APIs. Deprecated APIs can be removed in a major release. Clear documentation for the upgrade path is always provided.

Minor

Minor versions add features and functionality that are downward compatible with previous versions. Minor versions can adjust the extension framework and APIs. However, deprecated extension APIs stay in place and are not yet removed.

Patch

Patch versions (also known as bugfix releases) adjust functionality in a downward compatible manner and do not require any manual upgrade steps. These maintenance versions are drop-in replacements for the current minor version.

Hotfix Releases
Customers with professional support can receive hotfix releases that do not use semantic versioning. Hotfix releases are always customer-specific and are usually downward compatible. If a hotfix version requires any manual upgrade steps, all customers who receive the hotfix version get detailed instructions.

HiveMQ Rolling Upgrade Policy

HiveMQ releases a new long-term support (LTS) version every 18 months and ships a feature release and an LTS maintenance release each month.

To simplify the upgrade process and eliminate the need for time-consuming version-by-version upgrades, HiveMQ now provides enhanced version compatibility for all HiveMQ releases starting with the HiveMQ 4.9 LTS release:

  • All HiveMQ feature releases between two LTS releases support rolling upgrades. This policy gives you an 18-month window to upgrade, ensures backward feature compatibility, and provides zero downtimes.

  • Compatibility also extends from one LTS version to the next LTS version. You can smoothly upgrade from your current LTS version to the next one. For example, upgrade from HiveMQ 4.9.x LTS to HiveMQ 4.28.x LTS.

Here are some additional upgrade examples:

  • HiveMQ 4.9-LTS is compatible with the next 18 months of release versions. In this case, up to the release of the new LTS version, HiveMQ 4.28-LTS.

  • HiveMQ 4.9-LTS is not compatible with the HiveMQ version that is released 19 months later. In this case, the expected 4.29 release. This upgrade exceeds the 18-month limit and will require first an upgrade to 4.28-LTS.

  • HiveMQ 4.10 is compatible with any released version up to HiveMQ 4.29.

  • HiveMQ 4.10 is not compatible with 4.30 and will require first an upgrade to HiveMQ 4.28.

For more information, see our Introducing Flexible MQTT Platform Upgrades with HiveMQ blog post.

HiveMQ occasionally launches more than one feature release in a single month.
Due to special releases, there can be more than 18 HiveMQ versions between two LTS releases.