Exclusão de Dados do HiveMQ Serverless: Salve Retained Messages, Sessões e Credenciais Antes do Prazo

O HiveMQ informa que, depois da data de fim de vida do HiveMQ Cloud Serverless, exclui permanentemente todos os clusters Serverless e os dados neles, incluindo retained messages, sessões de clientes, credenciais de acesso e permissões, e que não consegue restaurar um cluster após a exclusão. Nada é migrado automaticamente para um novo broker. Se alguma parte do seu sistema depende de estado armazenado no broker, você precisa capturá-lo antes de 31 de dezembro de 2026.

Este guia explica quais dados estão em risco, como exportar retained messages com um script curto, como documentar credenciais e permissões e como projetar seus clientes para que o novo broker reconstrua o estado sozinho.

O que fica armazenado no seu cluster Serverless

Mensagens que não são retidas nem enfileiradas para uma sessão nunca são armazenadas, então não há nada a exportar delas: o histórico da sua telemetria fica no seu próprio banco de dados, não no broker. Se hoje você não armazena a telemetria em lugar nenhum, este é um bom momento para adicionar um assinante que a grave em um banco de dados.

Exporte retained messages com Python

A única forma de ler retained messages é assiná-las. Um cliente que assina # recebe todas as retained messages que tem permissão para ver, marcadas com retain=True. O script abaixo as coleta por alguns segundos e as grava em um arquivo JSON, codificando em base64 payloads binários como Sparkplug B. Ele usa 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"   # o hostname do seu HiveMQ Serverless
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:  # apenas mensagens armazenadas no 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)          # as retained messages chegam logo após a assinatura
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")

Execute-o com uma credencial que tenha permissão de assinatura em todos os topics. Se as suas permissões forem divididas, execute uma vez por credencial. Para árvores de topics muito grandes, aumente o tempo de espera até que a contagem pare de crescer.

Restaure as retained messages no novo broker

Quando o novo broker estiver criado, republique cada mensagem armazenada com a flag retain:

# 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")

O QoS é limitado a 1 aqui porque o plano Serverless gratuito suporta QoS até 1; no Serverless (Paid) e superiores você pode manter QoS 2. Depois, confira os topics no explorador de topics ao vivo da ConnectMQ. Tenha cuidado com retained messages que são comandos: restaurar um antigo comando "abrir válvula" pode disparar uma ação quando um dispositivo se reconectar. Revise a exportação e descarte tudo o que não deve ser reproduzido. O contexto sobre esse comportamento está em retained messages no MQTT.

Sessões persistentes não podem ser exportadas

O estado de sessão, ou seja, as assinaturas de um cliente e sua fila de mensagens não entregues, é interno ao broker. Não existe operação MQTT para exportá-lo. Em vez disso:

1. Garanta que os clientes assinem de novo a cada conexão, mesmo quando usam sessão persistente. A maioria das bibliotecas faz isso se você assinar no callback de conexão.
2. Migre os clientes em um período em que estejam online, para que as filas estejam vazias.
3. No novo broker, defina um session expiry interval adequado. Veja sessão persistente no MQTT e session expiry interval no MQTT.

Documente credenciais e permissões

Não é possível exportar senhas, mas você deve documentar o modelo de acesso antes que o console desapareça:

• Liste o nome de cada credencial e o que a utiliza (grupo de dispositivos, serviço, parceiro).
• Registre as suas permissões: em quais filtros de topic ela pode publicar ou assinar.
• Defina o mapeamento no novo broker. Na ConnectMQ, cada broker emite um usuário, uma senha e um client ID; os clientes podem usar o client ID com um _suffix para abrir várias conexões com um único conjunto de credenciais. Onde você dependia de permissões de topic para separar partes que não confiam entre si, use brokers separados por fronteira de confiança.

Guarde as novas credenciais em um gerenciador de segredos, não em uma planilha. O guia sobre como proteger credenciais MQTT nos dispositivos aborda o armazenamento no lado do dispositivo.

Torne o estado autorrecuperável em qualquer broker

A melhor solução de longo prazo é tornar os dispositivos responsáveis pelo próprio estado. Quando um dispositivo se conecta, ele deve publicar imediatamente o seu status atual, configuração e versão de firmware com a flag retain, e definir uma mensagem Last Will para que os assinantes saibam quando ele cai inesperadamente. Assim, uma troca de broker, um reinício ou uma migração nunca perde estado por mais de um ciclo de conexão. Veja Last Will and Testament no MQTT para conhecer o padrão.

Perguntas frequentes

O HiveMQ vai excluir meus dados em 1º de janeiro de 2027?

O HiveMQ informa que, depois da data de fim de vida, exclui permanentemente todos os clusters Serverless e seus dados, e que um cluster excluído não pode ser restaurado. Exporte o que precisar antes de 31 de dezembro de 2026.

Posso exportar o histórico de mensagens do meu HiveMQ Serverless?

O broker não guarda histórico de mensagens comuns; ele armazena apenas retained messages e mensagens enfileiradas em sessões. O histórico de telemetria precisa vir do seu próprio banco de dados ou armazenamento.

As retained messages restauradas vão parecer diferentes para os assinantes?

Não. Uma retained message restaurada com o mesmo topic e o mesmo payload é entregue aos novos assinantes exatamente como antes, com a flag retain ativada.

Devo excluir o meu cluster HiveMQ por conta própria?

Somente depois que todos os clientes estiverem rodando no novo broker e você tiver exportado o que precisa. O HiveMQ não consegue recriar um cluster excluído.