RabbitMQ Classic Queue Mirroring
Classic queue mirroring (also called HA queues) is a feature that replicates queue contents across multiple nodes in a RabbitMQ cluster. Without mirroring, a classic queue's messages exist only on one node. If that node fails, the queue and its messages become unavailable. Mirroring copies those messages to other nodes so the queue survives a node failure.
Important: Classic queue mirroring is considered a legacy feature as of RabbitMQ 3.9. Quorum Queues (Topic 35) are the modern, recommended replacement. However, many existing systems still use mirrored queues, so understanding this feature remains valuable.
How Mirroring Works
A mirrored queue has one primary (leader) node and one or more mirror (follower) nodes. Every write (publish, ack, nack) goes to the primary first. The primary then synchronises the change to all mirrors. If the primary node fails, one of the mirrors is automatically promoted to become the new primary.
Mirrored Queue "orders" (primary on Node1):
Producer
|
| publishes msg
v
[Node1 - PRIMARY] ----sync----> [Node2 - MIRROR]
----sync----> [Node3 - MIRROR]
Node1 goes down:
[Node2 - PROMOTED TO PRIMARY]
[Node3 - MIRROR]
Queue continues without interruption.
Setting Up Mirroring via Policies
Mirroring is configured through RabbitMQ policies, not queue arguments. A policy matches queue names by pattern and applies mirror settings automatically. This means you do not need to change application code — just set the policy and matching queues get mirrored.
Mirror to All Nodes (ha-mode: all)
rabbitmqctl set_policy HA-All ".*" '{"ha-mode":"all"}' --apply-to queues
Every queue on every vhost gets mirrored to all nodes. Safe but resource-intensive — each node holds a full copy of every message.
Mirror to Exactly N Nodes (ha-mode: exactly)
rabbitmqctl set_policy HA-Two ".*" '{"ha-mode":"exactly","ha-params":2,"ha-sync-mode":"automatic"}' --apply-to queues
Each queue has exactly 2 copies: one primary and one mirror. Adding ha-sync-mode: automatic means new mirrors synchronise automatically when a node rejoins the cluster.
Mirror to Specific Nodes (ha-mode: nodes)
rabbitmqctl set_policy HA-Nodes "^critical\." \
'{"ha-mode":"nodes","ha-params":["rabbit@node1","rabbit@node2"]}' \
--apply-to queues
Only queues whose names start with critical. are mirrored, and only to Node1 and Node2 specifically.
Synchronisation Modes
ha-sync-mode: manual (default)
When a new mirror joins (after a node restart), it starts empty. Messages are copied to the mirror only as new messages arrive. Old messages in the queue are not copied to the new mirror. The new mirror only becomes fully in sync gradually.
ha-sync-mode: automatic
When a new mirror joins, RabbitMQ synchronises all existing messages to it immediately. This provides stronger consistency but pauses the queue during sync — no messages are delivered to consumers while synchronisation runs. Use with caution on large queues.
Checking Mirroring Status
rabbitmqctl list_queues name policy pid slave_pids synchronised_slave_pids
name policy pid slave_pids sync_pids orders HA-Two <0.123.0> [<0.456.0>,<0.789.0>] [<0.456.0>]
slave_pids shows all mirrors. synchronised_slave_pids shows only fully synced mirrors. If a mirror is in slave_pids but not in synchronised_slave_pids, it is still catching up.
Promoted Primary After Node Failure
When the primary node fails, RabbitMQ automatically promotes a synchronised mirror to become the new primary. Consumers experience a brief reconnection period but can then continue consuming from the promoted primary. Messages that were in the original primary but not yet synced to any mirror at the time of failure are lost.
Why Quorum Queues Are Better
Classic Mirrored Queues Quorum Queues ----------------------------------------- Legacy approach Modern approach Eventual consistency Strong consistency (Raft) Can lose messages on failover No message loss on failover Manual sync management Automatic sync Higher resource overhead Lower, more predictable overhead Still works in RabbitMQ 3.x Recommended from 3.8 onwards
Removing a Policy
rabbitmqctl clear_policy HA-All
Removing a policy does not delete the queues — it just stops mirroring them. Existing mirrors gradually become standalone queues on their respective nodes.
Summary
Classic queue mirroring replicates queue messages across multiple nodes using a primary-mirror architecture. Configure mirroring via policies using ha-mode: all, exactly, or nodes. Use ha-sync-mode: automatic to ensure new mirrors receive existing messages. Mirrored queues provide high availability for classic queues, but Quorum Queues offer stronger consistency guarantees and are the preferred choice for all new deployments from RabbitMQ 3.8 onward.