Migrate message queue configuration

This guide provides migration instructions for message queue configuration across Adobe Commerce versions. Use these examples to update your env.php and XML configuration files when upgrading.

Migrate from 2.4.4 to 2.4.5+

Adobe Commerce 2.4.5 and later versions support Apache ActiveMQ Artemis (STOMP) as an alternative message broker to RabbitMQ (AMQP). When upgrading from 2.4.4 or earlier, you can continue using RabbitMQ or migrate to ActiveMQ Artemis.

Key changes in 2.4.5+

• ActiveMQ Artemis (STOMP) support—New message broker option alongside RabbitMQ
• Extended dynamic connection detection—Supports STOMP in addition to AMQP
• Enhanced SSL configuration—Improved SSL options for both brokers
• Multiple named connections—Configure multiple broker connections simultaneously

For STOMP connections, use ANYCAST addressing mode for point-to-point message delivery and load balancing across multiple consumers.

Configuration File Changes

The following table shows the key differences between 2.4.4 and 2.4.5+ configurations:

Update env.php Configuration

For RabbitMQ (AMQP) - No Changes Required:

Copy
'queue' => [
    'amqp' => [
        'host' => 'rabbitmq.example.com',
        'port' => '5672',
        'user' => 'magento',
        'password' => 'magento',
        'virtualhost' => '/',
        'ssl' => false
    ]
]
Copied to your clipboard
'queue' => [
    'amqp' => [
        'host' => 'rabbitmq.example.com',
        'port' => '5672',
        'user' => 'magento',
        'password' => 'magento',
        'virtualhost' => '/',
        'ssl' => false
    ]
]

For ActiveMQ Artemis (STOMP):

Copy
'queue' => [
    'stomp' => [
        'host' => 'activemq.example.com',
        'port' => '61613',
        'user' => 'artemis',
        'password' => 'artemis',
        'ssl' => false
    ]
]
Copied to your clipboard
'queue' => [
    'stomp' => [
        'host' => 'activemq.example.com',
        'port' => '61613',
        'user' => 'artemis',
        'password' => 'artemis',
        'ssl' => false
    ]
]

For both brokers (requires default_connection):

Copy
'queue' => [
    'default_connection' => 'amqp', // Required when multiple brokers are configured
    'amqp' => [
        'host' => 'rabbitmq.example.com',
        'port' => '5672',
        'user' => 'magento',
        'password' => 'magento',
        'virtualhost' => '/',
        'ssl' => false
    ],
    'stomp' => [
        'host' => 'activemq.example.com',
        'port' => '61613',
        'user' => 'artemis',
        'password' => 'artemis',
        'ssl' => false
    ]
]
Copied to your clipboard
'queue' => [
    'default_connection' => 'amqp', // Required when multiple brokers are configured
    'amqp' => [
        'host' => 'rabbitmq.example.com',
        'port' => '5672',
        'user' => 'magento',
        'password' => 'magento',
        'virtualhost' => '/',
        'ssl' => false
    ],
    'stomp' => [
        'host' => 'activemq.example.com',
        'port' => '61613',
        'user' => 'artemis',
        'password' => 'artemis',
        'ssl' => false
    ]
]

Update queue_consumer.xml files

All <consumer> attributes (name, queue, handler, consumerInstance, maxMessages) remain unchanged. The only difference is the connection attribute:

2.4.4 Example:

Copy
<consumer name="example.consumer" queue="example.queue" connection="amqp" maxMessages="100" />
Copied to your clipboard
<consumer name="example.consumer" queue="example.queue" connection="amqp" maxMessages="100" />

2.4.5+ Example (Uses default broker from env.php):

Copy
<consumer name="example.consumer" queue="example.queue" maxMessages="100" />
Copied to your clipboard
<consumer name="example.consumer" queue="example.queue" maxMessages="100" />

2.4.5+ Example (Explicitly specifies broker):

Copy
<!-- Force this consumer to use AMQP even if multiple brokers are configured -->
<consumer name="example.consumer" queue="example.queue" connection="amqp" maxMessages="100" />

<!-- Force this consumer to use STOMP even if multiple brokers are configured -->
<consumer name="example.consumer" queue="example.queue" connection="stomp" maxMessages="100" />
Copied to your clipboard
<!-- Force this consumer to use AMQP even if multiple brokers are configured -->
<consumer name="example.consumer" queue="example.queue" connection="amqp" maxMessages="100" />

<!-- Force this consumer to use STOMP even if multiple brokers are configured -->
<consumer name="example.consumer" queue="example.queue" connection="stomp" maxMessages="100" />

Update queue_publisher.xml files

The topic and disabled attributes remain unchanged. Key differences in 2.4.5+:

2.4.4 Example (RabbitMQ only):

Copy
<publisher topic="example.topic">
    <connection name="amqp" exchange="magento" />
</publisher>
Copied to your clipboard
<publisher topic="example.topic">
    <connection name="amqp" exchange="magento" />
</publisher>

2.4.5+ Example (RabbitMQ):

Copy
<publisher topic="example.topic">
    <connection name="amqp" exchange="magento" disabled="false"/>
    <connection name="db" disabled="true"/>
</publisher>
Copied to your clipboard
<publisher topic="example.topic">
    <connection name="amqp" exchange="magento" disabled="false"/>
    <connection name="db" disabled="true"/>
</publisher>

2.4.5+ Example (ActiveMQ Artemis):

Copy
<publisher topic="example.topic" queue="example.queue">
    <connection name="stomp" disabled="false"/>
    <connection name="db" disabled="true"/>
</publisher>
Copied to your clipboard
<publisher topic="example.topic" queue="example.queue">
    <connection name="stomp" disabled="false"/>
    <connection name="db" disabled="true"/>
</publisher>

Update queue_topology.xml files

All <exchange> and <binding> attributes (name, type, durable, autoDelete, id, topic, destinationType, destination) remain unchanged. The only difference is the connection attribute:

2.4.4 Example:

Copy
<exchange name="magento" type="topic" connection="amqp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>
Copied to your clipboard
<exchange name="magento" type="topic" connection="amqp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>

2.4.5+ Example (Uses default broker from env.php):

Copy
<exchange name="magento" type="topic">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>
Copied to your clipboard
<exchange name="magento" type="topic">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>

2.4.5+ Example (Explicitly specifies broker):

Copy
<!-- Force this exchange to use AMQP even if multiple brokers are configured -->
<exchange name="magento" type="topic" connection="amqp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>

<!-- Force this exchange to use STOMP even if multiple brokers are configured -->
<exchange name="magento" type="topic" connection="stomp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>
Copied to your clipboard
<!-- Force this exchange to use AMQP even if multiple brokers are configured -->
<exchange name="magento" type="topic" connection="amqp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>

<!-- Force this exchange to use STOMP even if multiple brokers are configured -->
<exchange name="magento" type="topic" connection="stomp">
    <binding id="example.binding" topic="example.topic" destinationType="queue" destination="example.queue"/>
</exchange>

Legacy migrations

The following sections document migration paths for older Adobe Commerce versions. These are provided for reference when upgrading from legacy installations.

Migrate from 2.1 to 2.2

To upgrade the message queues for Adobe Commerce or Magento Open Source 2.1, you must create the following files in the <module>/etc directory for each module that will use the message queue framework.

• queue_consumer.xml—Defines the relationship between an existing queue and its consumer.
• queue_topology.xml—Defines the message routing rules and declares queues and exchanges.
• queue_publisher.xml—Defines the exchange where a topic is published.

The existing queue.xml file is deprecated.

For complete details about these files, see Configure message queues

Create the queue_consumer.xml file

Create the queue_topology.xml file

Create the queue_publisher.xml file

Migrate from 2.0 to 2.2

To upgrade from Adobe Commerce or Magento Open Source 2.0, you must create the following files in the <module>/etc directory for each module that will use the message queue framework.

• queue_consumer.xml - Defines the relationship between an existing queue and its consumer.
• queue_topology.xml—Defines the message routing rules.
• queue_publisher.xml—Defines the relationship between a topic and its publisher.

The existing queue.xml file is deprecated.

For complete details about these files, see Configure message queues

Create the queue_consumer.xml file

Create the queue_topology.xml file

Create the queue_publisher.xml file

Last updated 9/8/2023

Was this helpful?

Yes

No