HiveMQ Cloud Serverless Migration Guide: Move Your MQTT Clients Step by Step

A HiveMQ Cloud Serverless migration is mostly a reconfiguration project: the MQTT protocol stays the same, but every client needs a new hostname, new credentials and possibly a new client ID, and any state that lived on the old cluster must be rebuilt. This guide walks through the full procedure in six steps, using a ConnectMQ private broker as the destination. The same steps apply to any standards-based MQTT broker.

If you have not read the background yet, start with HiveMQ Cloud Serverless end of life for the dates and what HiveMQ deletes after December 31, 2026.

Step 1: Inventory Everything That Connects

You cannot migrate what you have not listed. Open the HiveMQ Cloud console, note your cluster hostname and every access credential, then build a table with one row per client type:

Do not forget the quiet clients: a Node-RED flow on a forgotten Raspberry Pi, a Grafana or Telegraf input, a mobile app with a hard-coded hostname, or a partner that subscribes to one topic. The HiveMQ migration checklist contains a printable version of this inventory.

Step 2: Map Features to the New Broker

Compare your inventory with the destination plan before changing anything:

Two rows need a decision.

Client IDs. HiveMQ Cloud lets each client choose its own client ID. ConnectMQ binds the client ID to the issued credentials: a client may use exactly the issued client ID or a variant with a suffix, such as YOUR_CLIENT_ID_sensor140. Plan to give each device a suffix derived from its serial number or MAC address. See MQTT client ID best practices for patterns.

Permissions. If you used HiveMQ topic permissions to separate untrusted parties (for example, customers who must not see each other's data), do not try to reproduce that on a single broker. Use one broker per customer or trust boundary, or put a backend in between.

Step 3: Create the Destination Broker

1. Sign up at app.connectmq.com. The free Serverless plan needs no credit card, which is ideal for testing.
2. Choose a plan sized to your peak connection count plus headroom. Use Serverless (Paid) for production fleets up to 1,000 connections, or Dedicated for larger or latency-sensitive workloads. Our serverless alternative and managed cloud alternative guides help you choose.
3. Create the broker and copy the generated username, password and client ID.
4. Make the broker address configurable this time. Store hostname, port, credentials and client ID in a configuration file, provisioning service or OTA-updatable settings rather than in compiled firmware. A plain DNS alias under your own domain is not enough on its own for TLS, because the broker's certificate is issued for the provider hostname and clients that verify the hostname would reject it.

Step 4: Test With a Real Client

Before moving production clients, prove the basics with the same libraries your devices use. With mosquitto clients over TLS:

# Terminal 1: subscribe
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID_test1 \
  -t 'site1/#' -v

# Terminal 2: publish
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID_test2 \
  -t 'site1/room1/temp' -m '{"temp":21.7}' -q 1

Then test the details that matter for your fleet: QoS levels, retained messages, Last Will messages, persistent sessions if you use them, message sizes close to your largest payload, and latency from the network your devices actually use. The live topic explorer in the ConnectMQ portal shows each message as it arrives, which is the quickest way to confirm topic structures. Code examples for ESP32, Python, Node.js and Node-RED are in Reconfigure MQTT clients after HiveMQ.

Step 5: Dual-Run, Then Move in Waves

The safest migration keeps both brokers running and relays traffic between them, so a device on the old broker and an application on the new broker still see each other's messages. A small relay process subscribes on one broker and republishes on the other. We show a complete relay script and the wave order in Zero-downtime HiveMQ migration.

The recommended order is:

1. Consumers first. Move databases, rule engines, Node-RED flows and dashboards to the new broker. Thanks to the relay they still receive data from devices on the old cluster.
2. A pilot group of devices. A handful from different sites and firmware versions. Watch them for a few days.
3. The rest of the fleet in batches, with a checkpoint after each batch.
4. Command producers last, once the devices they control have moved.

During each wave, watch the connection count against your plan. If you exceed the quota, MQTT 5 clients receive reason code 0x97 (quota exceeded). Upgrade before a wave rather than during it.

Step 6: Cut Over and Clean Up

When the HiveMQ cluster shows no remaining client connections other than the relay:

1. Stop the relay.
2. Confirm that every expected topic is active on the new broker and that retained state has been republished.
3. Export anything you want to keep from the old cluster, such as a list of credentials for your records.
4. Delete the Serverless cluster, remembering that HiveMQ cannot recreate it.
5. Remove the old hostname from firmware defaults, documentation, runbooks and secrets stores.

Aim to finish well before December 31, 2026. A buffer of several weeks leaves room for devices that come online rarely, such as seasonal equipment or sensors that wake once a day.

Common Pitfalls

• Client ID collisions. Two devices using the same client ID will repeatedly disconnect each other on any broker. Derive suffixes from unique hardware identifiers.
• Hard-coded CA certificates. Devices that pin a specific CA bundle may reject a new broker's certificate. ConnectMQ uses a Let's Encrypt certificate; make sure the ISRG Root X1 root is in the device's trust store. See MQTT TLS configuration.
• Assuming retained state moves. It does not. Have devices publish their current state with the retain flag right after connecting.
• Forgetting reconnect logic. A device without proper backoff can flood a new broker during a wave. Review MQTT keep alive and your client's reconnect settings first.

Frequently Asked Questions

How long does a HiveMQ Serverless migration take?

For a handful of applications, a day. For fleets of field devices that need firmware updates, plan for weeks: building and testing new firmware, staged rollout and waiting for rarely connected devices. Start now so the deadline is not your test date.

Can I migrate without updating device firmware?

Only if the hostname, credentials and client ID are configurable without a firmware change, for example through a configuration file or a provisioning service. If they are compiled in, you need an over-the-air update.

Do I need to change my topic structure?

No. Topics are just strings, and ConnectMQ supports standard wildcards and up to the topic depths typical IoT designs use. Keep your existing structure so dashboards and rules keep working.

Which ConnectMQ plan should I start with?

Start with the free Serverless plan to test. For production, choose Serverless (Paid) for up to 1,000 connections, or the Dedicated Managed Cloud MQTT Broker when you need an isolated cluster.