HiveMQ Serverless Data Deletion: Save Retained Messages, Sessions and Credentials Before the Deadline

HiveMQ states that after the HiveMQ Cloud Serverless end-of-life date it permanently deletes all Serverless clusters and the data on them, including retained messages, client sessions, access credentials and permissions, and that it cannot restore a cluster after deletion. Nothing is moved to a new broker automatically. If any part of your system depends on state stored in the broker, you need to capture it before December 31, 2026.

This guide explains which data is at risk, how to export retained messages with a short script, how to document credentials and permissions, and how to design your clients so the new broker rebuilds state on its own.

What Lives on Your Serverless Cluster

Messages that are not retained and not queued for a session are never stored, so there is nothing to export there: the history of your telemetry lives in your own database, not in the broker. If you do not store telemetry anywhere today, now is a good moment to add a subscriber that writes it to a database.

Export Retained Messages With Python

The only way to read retained messages is to subscribe to them. A client that subscribes to # receives every retained message it is allowed to see, flagged with retain=True. The script below collects them for a few seconds and writes them to a JSON file, encoding binary payloads such as Sparkplug B as base64. It uses paho-mqtt 2.x:

# pip install "paho-mqtt>=2.0"
import base64, json, ssl, time
import paho.mqtt.client as mqtt

HOST = "YOUR_CLUSTER.s1.eu.hivemq.cloud"   # your HiveMQ Serverless hostname
USER, PASSWORD = "YOUR_HIVEMQ_USERNAME", "YOUR_HIVEMQ_PASSWORD"

retained = {}

def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe("#", qos=1)

def on_message(client, userdata, msg):
    if msg.retain:  # only messages stored on the broker
        retained[msg.topic] = {
            "qos": msg.qos,
            "payload_b64": base64.b64encode(msg.payload).decode(),
        }

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="retained-export-1",
                     protocol=mqtt.MQTTv5)
client.username_pw_set(USER, PASSWORD)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.on_connect = on_connect
client.on_message = on_message
client.connect(HOST, 8883)
client.loop_start()
time.sleep(10)          # retained messages arrive right after subscribing
client.loop_stop()
client.disconnect()

with open("retained-export.json", "w") as f:
    json.dump(retained, f, indent=2)
print(f"Saved {len(retained)} retained topics")

Run it with a credential that has subscribe permission on all topics. If your permissions are split, run it once per credential. For very large topic trees, increase the wait time until the count stops growing.

Restore Retained Messages on the New Broker

Once your new broker exists, republish each stored message with the retain flag:

# pip install "paho-mqtt>=2.0"
import base64, json, ssl, time
import paho.mqtt.client as mqtt

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID_restore",
                     protocol=mqtt.MQTTv5)
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.connect("broker.connectmq.com", 8883)
client.loop_start()

with open("retained-export.json") as f:
    retained = json.load(f)

for topic, item in retained.items():
    payload = base64.b64decode(item["payload_b64"])
    client.publish(topic, payload, qos=min(item["qos"], 1), retain=True).wait_for_publish()

client.loop_stop()
client.disconnect()
print(f"Restored {len(retained)} retained topics")

QoS is capped at 1 here because the free Serverless plan supports QoS up to 1; on Serverless (Paid) and above you can keep QoS 2. Check the topics in the ConnectMQ live topic explorer afterwards. Be careful with retained messages that are commands: restoring an old "open valve" command can trigger an action when a device reconnects. Review the export and drop anything that should not be replayed. Background on this behaviour is in MQTT retained messages.

Persistent Sessions Cannot Be Exported

Session state, meaning a client's subscriptions and its queue of undelivered messages, is internal to the broker. There is no MQTT operation to export it. Instead:

1. Make sure clients subscribe again on every connect, even when they use a persistent session. Most libraries do this if you subscribe in the connect callback.
2. Move clients during a period when they are online, so their queues are empty.
3. On the new broker, set an appropriate session expiry interval. See MQTT persistent session and MQTT session expiry interval.

Document Credentials and Permissions

You cannot export passwords, but you should document the access model before the console disappears:

• List every credential name and what uses it (device group, service, partner).
• Record its permissions: which topic filters it may publish or subscribe to.
• Decide the mapping on the new broker. On ConnectMQ, each broker issues a username, password and client ID; clients can use the client ID with a _suffix to run several connections under one credential set. Where you relied on topic permissions to separate untrusted parties, use separate brokers per trust boundary.

Store the new credentials in a secrets manager, not in a spreadsheet. The guide on securing MQTT credentials on devices covers device-side storage.

Make State Self-Healing on Any Broker

The best long-term fix is to make devices responsible for their own state. When a device connects, it should immediately publish its current status, configuration and firmware version with the retain flag, and set a Last Will message so subscribers learn when it goes offline unexpectedly. Then a broker change, a restart or a migration never loses state for longer than one connection cycle. See MQTT Last Will and Testament for the pattern.

Frequently Asked Questions

Does HiveMQ delete my data on January 1, 2027?

HiveMQ states that after the end-of-life date it permanently deletes all Serverless clusters and their data, and that a deleted cluster cannot be restored. Export what you need before December 31, 2026.

Can I export my HiveMQ Serverless message history?

The broker does not keep a history of ordinary messages; it only stores retained messages and queued session messages. Telemetry history must come from your own database or storage.

Will restored retained messages look different to subscribers?

No. A retained message restored with the same topic and payload is delivered to new subscribers exactly as before, with the retain flag set.

Should I delete my HiveMQ cluster myself?

Only after every client runs on the new broker and you have exported what you need. HiveMQ cannot recreate a deleted cluster.