MQTT State Durability

Keep MQTT state across restarts

By default, retained messages, persistent sessions, and queued QoS 1/2 traffic live in memory. A broker restart clears them. Durability writes that state to a local write-ahead log (WAL) so after a restart, clients can reconnect and pick up where they left off — their subscriptions, retained values, and any messages that were still waiting to be delivered.

Like a notebook next to a whiteboard. The whiteboard is fast working memory; the notebook is what you still have after the room goes dark. Durability is the notebook for MQTT state that must survive a restart.

When to enable durability

Enable durability when you need:

retained values to survive a broker restart;
persistent sessions and their subscriptions restored after reboot; or
queued QoS 1/2 messages re-offered to clients that reconnect with a persistent session.

Leave it off on constrained edge devices (slow flash, tight write budgets) or when restart persistence is not required.

Durability is a broker-level setting. It works on a standalone broker and on every cluster node. In a high-availability cluster (beta), enable it on every node: it keeps each node’s sessions and queued messages across restarts, and it lets subscriptions follow a client that reconnects to another node.

Configure the Durability section (or COREFLUX_DURABILITY_* environment variables), restart the broker, and verify retained or session state after a controlled restart.

Quick Start

Add a Durability block to the broker configuration, or set environment variables (env vars override the file). Restart the broker for changes to take effect.

Enable (typical)
Strongest fsync
Environment variables

Opt in with the default flush policy (group commit every 50 ms):

{
  "Durability": {
    "Enabled": true,
    "FsyncPolicy": "interval",
    "FsyncIntervalMs": 50,
    "Codec": "json"
  }
}

Flush every append when you need the smallest power-loss window on a single node:

{
  "Durability": {
    "Enabled": true,
    "FsyncPolicy": "always",
    "Codec": "json"
  }
}

Tune without editing the config file (useful in containers):

export COREFLUX_DURABILITY_ENABLED=true
export COREFLUX_DURABILITY_FSYNC=interval
export COREFLUX_DURABILITY_FSYNC_INTERVAL_MS=50
export COREFLUX_DURABILITY_CODEC=json
# optional: export COREFLUX_DURABILITY_DATA_DIR=/var/lib/coreflux/mqttwal

What is persisted

State	Survives restart?	Notes
Retained messages	Yes	Reloaded on boot on that node
Persistent sessions + subscriptions	Yes	A client that reconnects with a persistent session gets its subscriptions back
Queued QoS 1/2 (unacked)	Yes	Re-offered on session restore (at-least-once — a message acked at crash time may be redelivered)

QoS 0 traffic is not made durable by this layer — MQTT treats it as best-effort.

Configuration reference

Config field	Env var	Default	Description
`Enabled`	`COREFLUX_DURABILITY_ENABLED`	`false`	Master switch — opt in for restart durability
`FsyncPolicy`	`COREFLUX_DURABILITY_FSYNC`	`interval`	`interval` (group commit) or `always` (flush every append)
`FsyncIntervalMs`	`COREFLUX_DURABILITY_FSYNC_INTERVAL_MS`	`50`	Flush interval in ms when policy is `interval`
`Codec`	`COREFLUX_DURABILITY_CODEC`	`json`	Log encoding: `json` (readable) or `binary` (compact)
`DataDir`	`COREFLUX_DURABILITY_DATA_DIR`	`{data path}/mqttwal`	Root directory for durable MQTT state
`MaxSegmentBytes`	—	`8388608` (8 MiB)	Segment size that triggers rotation
`CheckpointEveryAppends`	—	`4096`	Appends between checkpoints that truncate older segments

Accept 1 / true (case-insensitive) for COREFLUX_DURABILITY_ENABLED.

Fsync policy

Policy	Behavior	Trade-off
`interval` (default)	Appends buffer and flush together on a timer	Bounded loss window on power failure only; process crashes still keep what the OS already had
`always`	Flush to disk on every append	Strongest single-node guarantee; every message waits for the disk, so it suits low message rates (and is costly on eMMC/SD edge devices)

Codec

json (default) — human-readable records; easier to inspect during debugging.
binary — compact encoding; smaller on disk and typically faster to encode/decode on busy brokers. Existing JSON segments still recover; new records append in binary. Switching back from binary to json for inspection of already-written binary segments is not supported — stay on json if you need text tooling on the log.

In a cluster, the same codec setting also applies to the replication logs used for quorum durability.

Performance

Durability is built so that you only pay for the state you choose to protect.

Clients	What durability does for them	Performance impact
Without a persistent session (MQTT 3.1.1 clean session, MQTT 5 session expiry 0)	Nothing to keep: the broker records nothing for them	None measurable
With a persistent session	Records each QoS 1/2 message queued for them, and its acknowledgement, so nothing is lost if the broker restarts	Grows with the rate of messages delivered to persistent sessions

In our tests with the default flush policy (one broker, QoS 1), average round-trip latency was unchanged, and fan-out to 20 persistent subscribers kept about two-thirds of the delivery rate it reached with durability off. FsyncPolicy: always waits for the disk on every write and is meant for low message rates.

Give persistent sessions only to the clients that must receive messages sent while they were offline. Traffic that reaches no persistent session costs nothing extra, even with durability on.

Durability and clustering

Durability and clustering (beta) protect different parts of a message’s path, and a cluster needs both:

Concern	What protects you
A node restarts	Durability on that node: its persistent sessions, their queued QoS 1/2 messages, and its retained messages are restored
A node fails after acknowledging a QoS ≥ 1 publish	Cluster quorum replication: the message is already stored on a majority of nodes
Messages published while a node is down	Clustering queues them for that node, and durability restores the sessions they are delivered to when it returns
A client reconnects to another node	Session takeover: requires durability so the client’s subscriptions follow it

Without durability, a cluster node that restarts comes back with no sessions. Messages that the other nodes kept for its persistent subscribers then have no session to go to, and are lost. See Durability and clustering on the clustering page.

Offline queues stay on the node that hosted them. Subscriptions follow a client that reconnects to another node (with durability enabled), but QoS 1/2 messages already queued for it are delivered only if it reconnects to the node that queued them. See clustering limitations.

Observability

Prometheus /metrics exposes durability and WAL series, including:

Metric family	What it shows
`coreflux_durability_enabled`	Whether durability is on
`coreflux_wal_*`	Appends, bytes written, fsyncs, last fsync latency
`coreflux_durable_*`	Counts for retained messages, sessions, in-flight messages, and in-flight drops

Use these alongside your usual broker health checks after enabling durability or changing fsync policy.

Limitations

Durability is opt-in. The default is Enabled: false. Without it, retained messages, sessions, and queued QoS 1/2 are lost on restart, and cluster session failover cannot restore subscriptions on another node.

Persistent sessions add disk work. Every QoS 1/2 message delivered to a persistent session is written to the log when it is queued and again when it is acknowledged. Plan disk throughput for your persistent-session message rate, and use FsyncPolicy: always only for low message rates. See Performance.

At-least-once after crash. A QoS 1/2 message acknowledged at the exact moment of failure may be redelivered after restore. Design consumers to tolerate duplicates.

Retained messages are kept per node. Durability restores each node’s own retained messages after a restart; it does not create a cluster-wide retained store. See clustering limitations.

Next Steps

High-Availability Clustering

Run multiple brokers with quorum replication and session failover on top of durability.

Broker Configuration

Ports, TLS, listeners, and other broker settings.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Keep MQTT state across restarts

When to enable durability

Quick Start

What is persisted

Configuration reference

Fsync policy

Codec

Performance

Durability and clustering

Observability

Limitations

Next Steps

High-Availability Clustering

Broker Configuration

​Keep MQTT state across restarts

​When to enable durability

​Quick Start

​What is persisted

​Configuration reference

​Fsync policy

​Codec

​Performance

​Durability and clustering

​Observability

​Limitations

​Next Steps

High-Availability Clustering

Broker Configuration

Keep MQTT state across restarts

When to enable durability

Quick Start

What is persisted

Configuration reference

Fsync policy

Codec

Performance

Durability and clustering

Observability

Limitations

Next Steps