EMQX Edge

English

简体中文

English

简体中文

Appearance

Contact Us

Retain Message Persistence Tutorial ​

This tutorial demonstrates how to configure and verify retain message persistence in EMQX Edge using SQLite. Retain message persistence ensures that messages marked with the retain flag remain available even after the broker restarts.

Configure SQLite in EMQX Edge ​

EMQX Edge uses SQLite to enable persistent storage of retained messages and QoS messages. Add the following section to your nanomq.conf configuration file:

hcl
sqlite {
    disk_cache_size = 102400           # Maximum number of messages to cache
    mounted_file_path = "/tmp/"        # Directory to store the cache files
    flush_mem_threshold = 3            # Number of messages before flushing to disk
    resend_interval = 5000             # Interval for resending messages (in milliseconds)
}

For a detailed explanation of each parameter, refer to the broker configuration.

To simplify the tutorial, we use a low flush_mem_threshold (3) to trigger disk flush quickly for demonstration purposes. In production, adjust this value based on your message throughput and storage capabilities.

Test Retain Message Persistence ​

This section walks you through testing the retention of messages using the MQTTX Client Tool. You will use a single connection for both publishing and subscribing to messages.

Start EMQX Edge ​

Launch EMQX Edge with your updated configuration file:

bash
$ nanomq start --conf path/to/nanomq.conf

Connect MQTTX to EMQX Edge ​

Open MQTTX and connect to your local EMQX Edge instance (e.g., localhost:1883):

Alt text

Publish Retained Messages ​

Send three retained messages to different topics. This will trigger the flush to disk, as configured.

Alt text

Restart EMQX Edge ​

Stop the broker with Ctrl+C, then restart it using the same configuration:

bash
$ nanomq start --conf path/to/nanomq.conf

Subscribe to Retain Message Topics ​

Reconnect via MQTTX and subscribe to the topics you previously published retained messages to. You should see the retained messages reappear, confirming they were persisted to disk and successfully reloaded after restart.

Alt text

Summary ​

You’ve successfully tested the retain message persistence in EMQX Edge using SQLite. This feature is essential for ensuring that retained messages survive broker restarts and are delivered to clients upon subscription.