HiveMQ Migration Checklist: Check Your Workload, Plan Credentials and Test a Private Broker

Moving off HiveMQ Cloud Serverless goes smoothly when three things are done before any device is touched: you know your workload, you have planned your new credentials, and you have tested a private broker with your real traffic. This checklist turns those three steps into concrete items you can tick off. It works with any destination broker; where it helps, we show how each item maps to ConnectMQ.

HiveMQ retires Serverless on December 31, 2026. For the background, read HiveMQ Cloud Serverless end of life.

Part 1: Check Your Workload

Your workload determines which plan you need and how long the migration takes.

Connections

• Peak concurrent connections on the HiveMQ cluster (check the console during your busiest hour).
• Expected growth over the next 12 to 18 months.
• Number of connections that are applications or dashboards rather than devices.
• Clients that open several connections (for example a gateway per site, or a backend with workers).

Messages

• Average and peak message rate.
• Largest payload size, including binary formats such as Sparkplug B.
• QoS levels in use; note any QoS 2 flows.
• Topics that use the retain flag, and whether retained state matters for startup.
• Clients that use persistent sessions and expect queued messages while offline.

Topology

• Full list of topic prefixes and who publishes or subscribes to each.
• Wildcard subscriptions used by backends.
• Shared subscriptions used for load balancing.
• Partners or customers that connect to your cluster.

How to Size the New Plan

Always size to peak plus headroom. A plan that fits the average will refuse connections during the reconnect storm after a network outage.

Part 2: Plan Your New Credentials

Your HiveMQ cluster URL and credentials cannot be moved, so every client gets new ones. Plan the scheme once rather than improvising per device.

• List every HiveMQ credential and what uses it.
• Map credentials to brokers. On ConnectMQ, each broker issues a username, password and client ID. Group clients that belong to the same trust boundary under one broker.
• Design client IDs. ConnectMQ binds the client ID to the credentials; clients may use the issued ID or add a suffix, such as YOUR_CLIENT_ID_line1-plc. Derive suffixes from a unique hardware identifier so two devices never collide. See MQTT client ID best practices.
• Separate trust boundaries. If you used HiveMQ topic permissions to isolate customers or partners from each other, give each one its own broker rather than one shared credential.
• Store secrets properly. Keep credentials in a secrets manager and on devices in protected storage, never in source control. See securing MQTT credentials on devices.
• Plan rotation. Decide how you will rotate credentials later without another migration. See rotate MQTT credentials.
• Make endpoints configurable. Hostname, port, credentials and client ID should be changeable remotely, so this is the last time you need firmware changes for a broker move.

Part 3: Test a Private Managed Broker

Never let the first production device be the first test. Create a private broker, for example a free one at app.connectmq.com, and work through these tests.

Connectivity

• Connect over TLS on port 8883 from each type of network your devices use.
• Connect over secure WebSocket on port 8084 (path /mqtt) from your web dashboard.
• Confirm devices trust the broker certificate. ConnectMQ uses Let's Encrypt; the ISRG Root X1 root must be in the trust store. See MQTT TLS configuration.

Behaviour

• Publish and subscribe with your real topic structure and payloads.
• Test each QoS level you use.
• Publish a retained message and confirm a new subscriber receives it.
• Set a Last Will message and kill the client to confirm it is delivered.
• Reconnect with a persistent session and confirm queued messages arrive.
• Send your largest payload.

Performance and Limits

• Measure round-trip latency from device locations, not only from the office.
• Reconnect a batch of test clients at once to simulate recovery after an outage.
• Confirm how your clients behave when a limit is hit; MQTT 5 clients receive reason code 0x97 for quota exceeded.
• Watch the test in the live topic explorer and dashboard.

A quick latency test with MQTT.js:

// npm install mqtt
const mqtt = require("mqtt");
const topic = "migration-test/rtt";
const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  username: process.env.MQTT_USERNAME,
  password: process.env.MQTT_PASSWORD,
  clientId: `${process.env.MQTT_CLIENT_ID}_rtt`,
  protocolVersion: 5,
});

let sentAt = 0, n = 0;
client.on("connect", () => client.subscribe(topic, { qos: 1 }, send));
function send() { sentAt = Date.now(); client.publish(topic, String(n), { qos: 1 }); }
client.on("message", () => {
  console.log(`round trip ${n}: ${Date.now() - sentAt} ms`);
  if (++n < 20) setTimeout(send, 250); else client.end();
});

Part 4: Go / No-Go Before the First Wave

• Inventory complete and owners identified for every client type.
• Plan chosen and sized to peak plus headroom.
• Credentials and client ID scheme documented.
• All tests in Part 3 passed.
• Retained state exported or republished by clients on connect. See HiveMQ Serverless data deletion.
• Relay for dual-running tested. See zero-downtime HiveMQ migration.
• Rollback plan: how a wave returns to HiveMQ if something fails, while the old cluster still works.
• Target date for the last wave, several weeks before December 31, 2026.

Once every box is ticked, follow the HiveMQ Serverless migration guide for the actual move.

Frequently Asked Questions

How do I find my peak connection count on HiveMQ Serverless?

Check the connection information in the HiveMQ Cloud console during your busiest period, and cross-check with your own device inventory. When in doubt, size the new plan generously.

Do I need one credential per device?

Not necessarily. On ConnectMQ, many devices can share one credential set by using unique client ID suffixes. Use separate brokers or credentials where devices or users belong to different trust boundaries.

Can I test ConnectMQ before paying?

Yes. The Serverless (Free) plan needs no credit card and supports up to 25 connections, which is enough to run every test in this checklist.

What if a test fails?

Fix it before moving production clients. Most failures are TLS trust stores, client ID rules or plan limits, and all three are easier to fix while the old cluster still works.