HiveMQ Upgrade Guides

HiveMQ Upgrade Guides show you how to upgrade from one HiveMQ broker version to another.
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
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 Release Cadence

HiveMQ releases a new long-term support (LTS) version of the HiveMQ Enterprise MQTT Broker approximately every 18 months and ships a feature release and an LTS maintenance release each month.
For more information, see Managing HiveMQ Releases and Support.

Rolling Upgrade Policy

To simplify the upgrade process and eliminate time-consuming version-by-version upgrades, HiveMQ offers increased version compatibility for all HiveMQ Enterprise MQTT Broker releases since HiveMQ 4.9 LTS:

  • Each monthly release is compatible with the next 18 monthly releases.

  • All HiveMQ Enterprise MQTT Broker feature releases between two LTS releases support rolling upgrades. This policy gives you an extended 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.28.x LTS to HiveMQ 4.55.x LTS.

Here are some additional upgrade examples:

  • HiveMQ 4.28 LTS is compatible with each version up to and including HiveMQ 4.55 LTS.

  • HiveMQ 4.28 LTS is not compatible with HiveMQ broker versions released after HiveMQ 4.55 LTS.
    To upgrade from HiveMQ 4.28 LTS to HiveMQ 4.56 or higher, you must first upgrade to HiveMQ 4.55 LTS.

  • Generally, each feature release is compatible for upgrades within an 18-month window.

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