Persistent Session and Queuing Messages - MQTT Essentials: Part 7

Written by The HiveMQ Team

Category: MQTT Essentials MQTT

Published: February 23, 2015


Welcome to the seventh part of the MQTT Essentials. A ten-part blog series on the core features and concepts of the MQTT protocol. In this post we talk about persistent sessions and message queueing in MQTT. Although MQTT is not a message queue by definition, it can queue messages for clients. We’ll show you how.

Persistent Session

To receive messages from an MQTT broker, a client connects to the broker and creates subscriptions to the topics in which it is interested. If the connection between the client and broker is interrupted during a non-persistent session, these topics are lost and the client needs to subscribe again on reconnect. Re-subscribing every time the connection is interrupted is a burden for constrained clients with limited resources. To avoid this problem, the client can request a persistent session when it connects to the broker. Persistent sessions save all information that is relevant for the client on the broker. The clientId that the client provides when it establishes connection to the broker identifies the session (more details).

What’s stored in a persistent session?

In a persistent session, the broker stores the following information (even if the client is offline). When the client reconnects the information is available immediately.

  • Existence of a session (even if there are no subscriptions).
  • All the subscriptions of the client.
  • All messages in a Quality of Service (QoS) 1 or 2 flow that the client has not yet confirmed.
  • All new QoS 1 or 2 messages that the client missed while offline.
  • All QoS 2 messages received from the client that are not yet completely acknowledged.

How do you start or end a persistent session?

When the client connects to the broker, it can request a persistent session. The client uses a cleanSession flag to tell the broker what kind of session it needs:

  • When the clean session flag is set to true, the client does not want a persistent session. If the client disconnects for any reason, all information and messages that are queued from a previous persistent session are lost.
  • When the clean session flag is set to false, the broker creates a persistent session for the client. All information and messages are preserved until the next time that the client requests a clean session. If the clean session flag is set to false and the broker already has a session available for the client, it uses the existing session and delivers previously queued messages to the client.

For more information on the connection establishment between client and broker, see part 3 of MQTT Essentials.

How does the client know if a session is already stored?

Since MQTT 3.1.1, the CONNACK message from the broker contains a session present flag. This flag tells the client if a previously established session is still available on the broker. For more information on connection establishment, see part 3 of MQTT Essentials.

Persistent session on the client side

Similar to the broker, each MQTT client must also store a persistent session. When a client requests the server to hold session data, the client is responsible for storing the following information:

  • All messages in a QoS 1 or 2 flow, that are not yet confirmed by the broker.
  • All QoS 2 messages received from the broker that are not yet completely acknowledged.

Best practices

Here are some guidelines that can help you decide when to use a persistent session or a clean session:

Persistent Session

  • The client must get all messages from a certain topic, even if it is offline. You want the broker to queue the messages for the client and deliver them as soon as the client is back online.
  • The client has limited resources. You want the broker to store the subscription information of the client and restore the interrupted communication quickly.
  • The client needs to resume all QoS 1 and 2 publish messages after a reconnect.

Clean session

  • The client needs only to publish messages to topics, the client does not need to subscribe to topics.You don’t want the broker to store session information or retry transmission of QoS 1 and 2 messages.
  • The client does not need to get messages that it misses offline.

How long does the broker store messages?

People often ask how long the broker stores the session. The easy answer is: The broker stores the session until the clients comes back online and receives the message. However, what happens if a client does not come back online for a long time? Usually, the memory limit of the operating system is the primary constraint on message storage. There is no standard answer for this scenario. The right solution depends on your use case. For example, in HiveMQ we provide a possibility to purge queued messages.


That finishes part seven in our MQTT Essentials series. Thanks for joining us. Next week, we’ll cover the concept of retained messages and how they work in MQTT. If you’ve already tried MQTT, you probably noticed the retained flag when you were sending a message. In our next post, you can learn all about them.

Have a great week and see you on the next MQTT Monday!

If you like the MQTT Essentials series, sign up for our newsletter to get notified as soon as a new post is available. If you prefer RSS, subscribe to our RSS feed here.

About The HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!
Contact us
<  Quality of Service 0,1 & 2 - MQTT Essentials: Part 6   |   Retained Messages - MQTT Essentials: Part 8   >