Skip to main content
HiveMQ can persist MQTT data either to disk or keep it in memory. The persistence mode determines how retained messages, queued messages, and client session data are stored.

​
Configuration Section

Persistence is configured within the <persistence> element: 
<hivemq>
    <persistence>
        <mode>file</mode>
    </persistence>
</hivemq>

​
Persistence Modes

HiveMQ Community Edition supports two persistence modes:

​
File-Based Persistence (Default)

<persistence>
    <mode>file</mode>
</persistence>
Characteristics:
  • Data is persisted to disk in the data directory
  • Survives HiveMQ restarts
  • Durable and reliable
  • Suitable for production environments
  • Slightly slower than in-memory mode
Default: file

​
In-Memory Persistence

<persistence>
    <mode>in-memory</mode>
</persistence>
Characteristics:
  • All data is stored in RAM
  • Faster performance
  • Data is lost on HiveMQ restart
  • Suitable for testing and development
  • Not recommended for production

​
What Gets Persisted

The following data is affected by the persistence mode:
  • Client Sessions - Session state for connected and disconnected clients
  • Queued Messages - QoS 1 and QoS 2 messages queued for delivery
  • Retained Messages - Messages published with the retain flag
  • Subscriptions - Client subscriptions
  • Message Metadata - Message expiry, publish timestamps, etc.

​
Data Directory

When using file-based persistence, HiveMQ stores data in: 
<HIVEMQ_HOME>/data/
This directory contains:
  • persistence/ - Retained messages and client session data
  • queued_messages/ - Messages queued for delivery

​
Performance Considerations

​
File-Based Persistence

Advantages:
  • Data durability and reliability
  • Survives crashes and restarts
  • Suitable for production workloads
Considerations:
  • Disk I/O can be a bottleneck
  • Requires sufficient disk space
  • SSD storage recommended for better performance

​
In-Memory Persistence

Advantages:
  • Fastest performance
  • No disk I/O overhead
  • Ideal for testing and ephemeral workloads
Considerations:
  • All data lost on restart
  • Limited by available RAM
  • Not suitable for production

​
Use Cases

​
File-Based Persistence

Use file-based persistence for:
  • Production deployments
  • When data durability is required
  • Long-lived client sessions
  • Retained messages that must survive restarts

​
In-Memory Persistence

Use in-memory persistence for:
  • Development and testing
  • Temporary or disposable data
  • High-performance scenarios where data loss is acceptable
  • Docker containers that don’t need state

​
Configuration Examples

​
Production Configuration

<hivemq>
    <persistence>
        <mode>file</mode>
    </persistence>
</hivemq>

​
Development/Testing Configuration

<hivemq>
    <persistence>
        <mode>in-memory</mode>
    </persistence>
</hivemq>

​
Switching Persistence Modes

When switching from file-based to in-memory persistence:
  1. Stop HiveMQ
  2. Update the configuration
  3. Optionally remove the data directory
  4. Start HiveMQ
When switching from in-memory to file-based persistence:
  1. Stop HiveMQ
  2. Update the configuration
  3. Start HiveMQ (a new data directory will be created)
Warning: All persisted data will be lost when switching modes.

​
Monitoring Persistence

Monitor the following to ensure healthy persistence:

​
File-Based

  • Disk space usage in the data directory
  • Disk I/O metrics
  • Write latency

​
In-Memory

  • JVM heap usage
  • Garbage collection metrics
  • Available RAM

​
Best Practices

  1. Use file-based persistence in production for data durability
  2. Use SSD storage for better file-based persistence performance
  3. Monitor disk space when using file-based persistence
  4. Allocate sufficient heap when using in-memory persistence
  5. Backup the data directory regularly (file-based mode)
  6. Test failover scenarios to ensure your persistence configuration meets requirements

Build docs developers (and LLMs) love

Get started for freeTalk to us