Skip to main content

Multi-Vhost Backup

RabbitMQ uses virtual hosts (vhosts) to provide logical separation between applications. This example shows how to back up queues from multiple vhosts in a single run.

Prerequisites​

  • RabbitMQ running with the Management Plugin enabled
  • Multiple vhosts configured
  • rabbitmq-backup installed

Step 1: Set Up Test Vhosts and Queues​

Create multiple vhosts with queues:

# Create vhosts
rabbitmqctl add_vhost production
rabbitmqctl add_vhost staging

# Grant permissions to the backup user
rabbitmqctl set_permissions -p production guest ".*" ".*" ".*"
rabbitmqctl set_permissions -p staging guest ".*" ".*" ".*"

# Create queues in each vhost
rabbitmqadmin -V production declare queue name=orders-queue durable=true
rabbitmqadmin -V production declare queue name=payments-queue durable=true
rabbitmqadmin -V staging declare queue name=orders-queue durable=true
rabbitmqadmin -V staging declare queue name=test-queue durable=true

# Publish test messages
for i in $(seq 1 20); do
  rabbitmqadmin -V production publish exchange=amq.default routing_key=orders-queue \
    payload="Production order $i"
  rabbitmqadmin -V production publish exchange=amq.default routing_key=payments-queue \
    payload="Production payment $i"
  rabbitmqadmin -V staging publish exchange=amq.default routing_key=orders-queue \
    payload="Staging order $i"
done

Verify:

rabbitmqadmin -V production list queues name messages
rabbitmqadmin -V staging list queues name messages

Step 2: Back Up All Vhosts​

Option A: Specify Vhosts Explicitly​

List the vhosts you want to include:

multi-vhost-backup.yaml
mode: backup
backup_id: "multi-vhost-001"

source:
  amqp_url: "amqp://guest:guest@localhost:5672/%2f"
  management_url: "http://localhost:15672"
  management_username: guest
  management_password: guest
  queues:
    include:
      - "*"
    vhosts:
      - "production"
      - "staging"

storage:
  backend: filesystem
  path: /tmp/rabbitmq-backups

backup:
  compression: zstd
  include_definitions: true
  stop_at_current_depth: true

Option B: Back Up All Vhosts (No Filter)​

Omit the vhosts field to back up queues from all vhosts the user has access to:

source:
  queues:
    include:
      - "*"
    # No vhosts filter = all accessible vhosts

Step 3: Run the Backup​

rabbitmq-backup backup -v --config multi-vhost-backup.yaml

Expected output:

INFO  Starting backup multi-vhost-001
INFO  Connected to RabbitMQ at localhost:5672
DEBUG Discovered vhosts: [/, production, staging]
DEBUG Found queue: orders-queue (production, classic, 20 messages)
DEBUG Found queue: payments-queue (production, classic, 20 messages)
DEBUG Found queue: orders-queue (staging, classic, 20 messages)
DEBUG Found queue: test-queue (staging, classic, 0 messages)
DEBUG Skipping test-queue (0 messages, below min_messages threshold)
INFO  Backing up 3 queues across 2 vhosts
INFO  Segment segment-0001.zst written (20 records) [production/orders-queue]
INFO  Segment segment-0001.zst written (20 records) [production/payments-queue]
INFO  Segment segment-0001.zst written (20 records) [staging/orders-queue]
INFO  Backup multi-vhost-001 completed: 60 messages in 3 segments

Step 4: Inspect the Backup Layout​

find /tmp/rabbitmq-backups/multi-vhost-001 -type f
/tmp/rabbitmq-backups/multi-vhost-001/manifest.json
/tmp/rabbitmq-backups/multi-vhost-001/definitions/definitions.json.zst
/tmp/rabbitmq-backups/multi-vhost-001/queues/production/orders-queue/segment-0001.zst
/tmp/rabbitmq-backups/multi-vhost-001/queues/production/payments-queue/segment-0001.zst
/tmp/rabbitmq-backups/multi-vhost-001/queues/staging/orders-queue/segment-0001.zst

Messages from each vhost are stored in separate directories under queues/{vhost}/.

Step 5: Describe the Backup​

rabbitmq-backup describe --path /tmp/rabbitmq-backups --backup-id multi-vhost-001 --format json

The output shows per-queue, per-vhost details:

{
  "backup_id": "multi-vhost-001",
  "total_messages": 60,
  "queues": [
    { "name": "orders-queue", "vhost": "production", "message_count": 20 },
    { "name": "payments-queue", "vhost": "production", "message_count": 20 },
    { "name": "orders-queue", "vhost": "staging", "message_count": 20 }
  ]
}

Step 6: Restore Specific Vhosts​

Restore Everything​

restore-all-vhosts.yaml
mode: restore
backup_id: "multi-vhost-001"

target:
  amqp_url: "amqp://guest:guest@localhost:5672/%2f"
  management_url: "http://localhost:15672"
  management_username: guest
  management_password: guest

storage:
  backend: filesystem
  path: /tmp/rabbitmq-backups

restore:
  restore_definitions: true
  publish_mode: direct-to-queue
  publisher_confirms: true

Remap Vhosts During Restore​

Restore the staging vhost data into a new staging-v2 vhost:

restore-remap-vhost.yaml
mode: restore
backup_id: "multi-vhost-001"

target:
  amqp_url: "amqp://guest:guest@localhost:5672/%2f"
  management_url: "http://localhost:15672"
  management_username: guest
  management_password: guest

storage:
  backend: filesystem
  path: /tmp/rabbitmq-backups

restore:
  restore_definitions: false
  publish_mode: direct-to-queue
  publisher_confirms: true
  vhost_mapping:
    staging: staging-v2
  create_missing_queues: true

Before restoring, create the target vhost:

rabbitmqctl add_vhost staging-v2
rabbitmqctl set_permissions -p staging-v2 guest ".*" ".*" ".*"

Then restore:

rabbitmq-backup restore --config restore-remap-vhost.yaml

Selective Backup with Queue Filters​

Combine vhost selection with queue name patterns:

source:
  queues:
    include:
      - "orders-*"       # Only queues matching this pattern
    exclude:
      - "*-dead-letter"  # Skip dead-letter queues
    vhosts:
      - "production"     # Only this vhost
    min_messages: 1       # Skip empty queues

Cleanup​

rabbitmqctl delete_vhost production
rabbitmqctl delete_vhost staging
rabbitmqctl delete_vhost staging-v2 2>/dev/null
rm -rf /tmp/rabbitmq-backups