3.0.x to 3.1.x Migration Guide

This is a major HiveMQ upgrade. HiveMQ 3.1 is not a drop in replacement for HiveMQ 3.0.x

Manual steps are required for upgrading from HiveMQ 3.0 to HiveMQ 3.1.

HiveMQ Upgrade

  • Create a backup of the entire HiveMQ installation folder

  • Install HiveMQ 3.1 as described in the HiveMQ Installation Guide

  • Migrate the configuration file contents of your old HiveMQ installation

  • To migrate the persistent data, copy all contents in the data folder from your backup to the new HiveMQ 3.1 data folder. On first start HiveMQ 3.1 will migrate the persistent data from your previous installation into its new persistent storage.

Configuration File Upgrade

HiveMQ 3.1 introduces some changes to the configuration file:

Cluster configuration

HiveMQ 3.1 introduces a much simpler way to configure a cluster directly in HiveMQ’s config.xml.

This configuration is not compatible with the previous way of configuring a HiveMQ cluster.

Please see the HiveMQ Clustering Documentation on how to configure your cluster for HiveMQ 3.1.

Persistent Data Migration

HiveMQ 3.1 introduces automatic migrations for persistent data between versions.

To allow HiveMQ to migrate the persistent data from previous versions you have to copy the contents of your data folder from the previous installation to the data folder of the new installation.

Linux example
cp -r /opt/hivemq-3.0.3/data/* /opt/hivemq-3.1.0/data/

On the first start up HiveMQ 3.1 will automatically migrate the persistent data from your previous installation into its new persistent storage.

Cluster Upgrade

In HiveMQ 3.1 the clustering underwent significant changes. HiveMQ clustering is not full-replication by default anymore. This allows for better distribution and significantly better scalability.

The cluster of HiveMQ 3.0 and HiveMQ 3.1 are not compatible. Rolling upgrades are not supported.

Please see the HiveMQ Clustering Documentation for more information on the new clustering options.

Plugin System Upgrade

The plugin system significantly improved in HiveMQ 3.1.

New Features

The HiveMQ 3 plugin systems has the following new features and improvements:

  • New Blocking and Async APIs for services. The previous services are deprecated but still work. They will be removed in HiveMQ 4.0. You should consider updating to the Async APIs for better performance.

  • The SharedSubscription service is deprecated, please use the new shared subscription logic introduced in HiveMQ 3.1 instead.

  • MetricService is now able to get Metrics from all cluster nodes.

Upgrading your plugins

In order to upgrade your plugin, execute the following steps:

  • Update your pom.xml

Adapt your pom.xml file

Change your HiveMQ SPI version to 3.1.0 in your pom.xml file

<dependency>
    <groupId>com.hivemq</groupId>
    <artifactId>hivemq-spi</artifactId>
    <version>3.1.0</version>
</dependency>