RabbitMQ
Strictly speaking, AMQP (and 0.9.1 version used) is a protocol, not a full-fledged driver, so you can use any servers that support this protocol (on your own, only rabbitmq was tested), such as:
However, it is recommended to use RabbitMQ as the main implementation, and reliable performance with other implementations is not guaranteed.
To install and configure the RabbitMQ, use the corresponding documentation page.
Named Connections
Define each connection under amqp.<name>. Each entry requires an explicit addr with a connection DSN. Each entry can also have an optional tls section. Every YAML AMQP pipeline must set config.connection to a configured name.
RR rejects pipeline creation if the connection selector is missing or empty. An unknown connection name also causes an error. RR also rejects a selected connection with a missing or empty addr.
There is no implicit default connection or localhost fallback. Top-level amqp.addr and amqp.tls are not supported. Connection names select configuration. Each pipeline keeps its own broker sockets.
Connection names are separate from named worker pools. Connection selection does not add a message header.
TLS options belong under amqp.<name>.tls:
key: path to a key file.cert: path to a certificate file.root_ca: path to Root CAs used by the AMQP client to trust and verify the broker/server certificate during TLS dial.client_auth_type: possible values areno_client_cert,request_client_cert,require_any_client_cert,verify_client_cert_if_given,require_and_verify_client_cert. This setting does not control broker certificate verification.
Configure RabbitMQ TLS support on the broker.
root_ca adds trust roots for broker certificate verification. Reconnects reuse the configured TLS settings. Use an amqps:// address with valid key and cert files. A root_ca-only TLS block is not supported. Omit tls when using a plain amqp:// connection.
Configure each pipeline's exchange and queue as shown below.
Pipeline Configuration
Static AMQP configuration uses only nested exchange and queue sections under jobs.pipelines.<name>.config. At least one section is required. Missing sections receive default values.
AMQP config.version is removed. Keep the root version: "3". Use the migration table to move old flat entity settings.
Options in config
connection: required connection name fromamqp.priority: pipeline priority. If a job has priority0, it inherits the pipeline priority. Default:10.prefetch: RabbitMQ QoS prefetch. Default:10.redial_timeout: reconnect timeout in seconds. Default:60.
Zero or negative values for priority, prefetch, and redial_timeout use their defaults.
Exchange settings
name: exchange name. Default:amqp.default.type: exchange type. Supported:direct,fanout,topic,headers. Default:direct.durable: durable exchange flag. Default:false.auto_delete: auto-delete exchange when last queue is unbound. Default:false.declare: declare exchange during pipeline creation. Default:true.
Queue settings
name: queue name. Optional for producer-only pipelines; required forrun,resume, andpause.routing_key: routing key. Required whenexchange.type != fanout.durable: durable queue flag. Default:false.auto_delete: auto-delete queue after the last consumer unsubscribes. Default:false.exclusive: exclusive queue flag. Default:false.consumer_id: consumer identifier. Default:roadrunner-<uuid>.delete_on_stop: delete queue when pipeline stops. Default:false.multiple_ack: ACK this and prior unacked deliveries on the same channel. Default:false.requeue_on_fail: use RabbitMQ requeue on failure (Nack). Default:false.headers: queue declaration arguments (for example,x-queue-mode: lazy).declare: declare and bind queue whenRunorResumestarts consumption. Default:true.
For both entities, an omitted declare has the same effect as true. Explicit false disables declaration. Pipeline creation does not declare or bind the queue.
This example consumes from brokerA through consume-a. It publishes to brokerB through publish-b.
Only consume-a is in jobs.consume. The producer-only publish-b pipeline has no queue name. Create a destination queue on broker B before publishing. Bind it to team-b-exchange with routing key team-b.
RR does not provide a cross-broker transaction. A failure after publishing to B but before acknowledging on A can cause duplicate messages on B. Make the destination handler safe to repeat.
Per-job Routing
Set the x-routing-key job header to override queue.routing_key for one publish. Supply exactly one nonempty string value. RR removes this header before it sends the message. Missing, empty, or multiple values use the pipeline's routing key.
The pool job header selects a PHP worker pool. It does not select an AMQP connection, exchange, or routing key. The rr_connection key selects a connection only during RPC pipeline declaration.
Read-only RabbitMQ Permissions
Disable declarations when the RabbitMQ user has no configure permission:
jobs.pipelines.<name>.config.exchange.declare: falsejobs.pipelines.<name>.config.queue.declare: false
Create the exchange, queue and binding before starting RR. The broker user still needs read permission to consume and write permission to publish. Keep queue.delete_on_stop: false to avoid a queue deletion request.
With queue.declare: false, RR skips both queue binding and passive queue inspection. jobs.Stat reports active: 0 without querying queue depth. This does not mean the queue is empty.
Delayed publishing and delayed requeue still declare and bind temporary queues. These operations still require configure permission.
Runtime Declaration
Dynamic pipeline declaration over RPC remains a flat string map. It is separate from static YAML configuration. It does not use nested config.exchange or config.queue sections.
The jobs.Declare payload accepts these declaration controls as strings:
exchange_declare:"true"(default) or"false".queue_declare:"true"(default) or"false".
Set the flat connection field to a configured name such as "brokerB". Do not send a DSN or TLS settings in the RPC payload.
The existing PHP 4.x AMQPCreateInfo API accepts queueHeaders. Jobs serializes this map as JSON in the flat queue_headers field. Set the reserved rr_connection key in that map to select a connection. No PHP package change is required.
RR reads rr_connection only when the flat connection field is absent. The flat field takes precedence whenever it is present, even when it is empty. An empty value causes an error. RR removes the reserved key from queue arguments before broker declaration and configuration storage. Other queue arguments stay unchanged. This key is RPC configuration metadata, not a message header. YAML pipelines must still set config.connection.
This runtime example creates the runtime-b pipeline on brokerB and declares its exchange. It does not declare or bind the queue. PHP 4.x Jobs requires an RPC instance:
Call $jobs->resume('runtime-b') after creation to declare and bind the queue and start consumption. For a producer-only pipeline, omit this call. Its destination queue and binding must exist before publishing.
Migration
To update an existing configuration:
Move
amqp.addrtoamqp.<name>.addr. Move optionalamqp.tlstoamqp.<name>.tls. Set an explicit address for each connection.Set
config.connectionon every YAML AMQP pipeline. There is no implicit default connection or localhost fallback.Remove
config.versionfrom every YAML AMQP pipeline. Keep the rootversion: "3".For runtime declarations, send flat
connectionor use the existing PHPqueueHeadersmap withrr_connection. The flat field takes precedence even when empty. RR removes the reserved key before broker declaration and configuration storage.
Move old flat entity settings to the nested fields below. All paths are relative to jobs.pipelines.<name>.config.
exchange
exchange.name
exchange_type
exchange.type
exchange_durable
exchange.durable
exchange_auto_delete
exchange.auto_delete
queue
queue.name
durable
queue.durable
queue_auto_delete
queue.auto_delete
delete_queue_on_stop
queue.delete_on_stop
queue_headers
queue.headers
routing_key, exclusive, consumer_id, multiple_ack, requeue_on_fail
Same key under queue
Keep priority, prefetch and redial_timeout directly in config.
The configuration schema rejects config.version and removed flat keys. The normal config provider can ignore unknown keys, but old scalar exchange or queue values fail to decode. Flat flags do not set nested values. For example, a flat durable: true does not set queue.durable. Migrate all entity settings before starting RR.
For restricted RabbitMQ permissions, set exchange.declare: false and queue.declare: false. Review the declaration limitations before using delayed jobs.
What's Next?
Queues and Jobs overview - Review the full jobs pipeline model before configuring AMQP in production.
Read-only RabbitMQ permissions - See declaration flags for restricted users. Use Runtime Declaration for flat
jobs.Declarekeys.Pipeline configuration - Use nested AMQP entity settings. See RoadRunner configuration for the general configuration structure.
Exchange settings and Queue settings - Review routing and consumption settings.
Allocate Timeout and CRC validation failed - Use these troubleshooting references when workers fail to process queue jobs as expected.
Last updated