Skip to main content

Basic Backup & Restore

This example walks through a complete backup and restore cycle using local filesystem storage. By the end, you will have backed up messages from RabbitMQ, inspected the backup, and restored messages to the same or a different broker.

Prerequisites​

  • RabbitMQ running locally with the Management Plugin enabled
  • rabbitmq-backup installed (see Bare Metal deployment)

Step 1: Set Up a Test Queue with Messages​

Create a queue and publish some test messages:

# Declare a queue
rabbitmqadmin declare queue name=demo-queue durable=true

# Declare an exchange and binding
rabbitmqadmin declare exchange name=demo-exchange type=direct
rabbitmqadmin declare binding source=demo-exchange destination=demo-queue routing_key=demo

# Publish test messages
for i in $(seq 1 50); do
  rabbitmqadmin publish exchange=demo-exchange routing_key=demo \
    payload="Message number $i at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
done

# Verify messages are in the queue
rabbitmqadmin list queues name messages

Expected output:

+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 50       |
+------------+----------+

Step 2: Create the Backup Configuration​

backup.yaml
mode: backup
backup_id: "demo-backup-001"

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

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

backup:
  compression: zstd
  compression_level: 3
  prefetch_count: 100
  requeue_strategy: cancel
  max_concurrent_queues: 4
  include_definitions: true
  stop_at_current_depth: true

Step 3: Run the Backup​

rabbitmq-backup backup --config backup.yaml

Expected output:

INFO  Starting backup demo-backup-001
INFO  Connected to RabbitMQ at localhost:5672
INFO  Discovered 1 queue matching selection criteria
INFO  Backing up queue demo-queue (50 messages)
INFO  Segment segment-0001.zst written (50 records)
INFO  Definitions exported (1 vhost, 1 queue, 1 exchange)
INFO  Backup demo-backup-001 completed: 50 messages in 1 segment

Step 4: Verify Messages Are Still in the Queue​

The backup is non-destructive. Messages remain in the queue:

rabbitmqadmin list queues name messages
+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 50       |
+------------+----------+

Step 5: Inspect the Backup​

List Backups​

rabbitmq-backup list --path /tmp/rabbitmq-backups
Backups in /tmp/rabbitmq-backups:
  demo-backup-001    2025-01-15T10:30:00Z    50 messages    1 queue

Describe the Backup​

rabbitmq-backup describe --path /tmp/rabbitmq-backups --backup-id demo-backup-001

Validate Integrity​

rabbitmq-backup validate --path /tmp/rabbitmq-backups --backup-id demo-backup-001 --deep

View the Storage Layout​

find /tmp/rabbitmq-backups/demo-backup-001 -type f
/tmp/rabbitmq-backups/demo-backup-001/manifest.json
/tmp/rabbitmq-backups/demo-backup-001/definitions/definitions.json.zst
/tmp/rabbitmq-backups/demo-backup-001/queues/_default/demo-queue/segment-0001.zst

Step 6: Restore from Backup​

Create the Restore Configuration​

restore.yaml
mode: restore
backup_id: "demo-backup-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: exchange
  publisher_confirms: true
  max_concurrent_queues: 4
  produce_batch_size: 100
  checkpoint_state: /tmp/rabbitmq-backups/demo-restore-checkpoint.db
  dry_run: false

Prepare: Clear the Queue (to Demonstrate Restore)​

Purge the queue to simulate data loss:

rabbitmqadmin purge queue name=demo-queue

# Confirm queue is empty
rabbitmqadmin list queues name messages
+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 0        |
+------------+----------+

Run the Restore​

rabbitmq-backup restore --config restore.yaml

Expected output:

INFO  Starting restore from demo-backup-001
INFO  Connected to RabbitMQ at localhost:5672
INFO  Current target definitions rollback snapshot written to demo-backup-001/definitions/rollback-before-import-...
INFO  Definitions restored (1 vhost, 1 queue, 1 exchange)
INFO  Restoring 50 messages to demo-queue
INFO  Published 50 messages to demo-queue (50 confirmed)
INFO  Restore complete: 50 messages restored

Verify the Restore​

rabbitmqadmin list queues name messages
+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 50       |
+------------+----------+

Consume a message to verify content:

rabbitmqadmin get queue=demo-queue count=1

Step 7: Restore to a Different Queue​

You can restore messages to a different queue using queue_mapping:

restore-remap.yaml
mode: restore
backup_id: "demo-backup-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
  queue_mapping:
    demo-queue: demo-queue-copy
  create_missing_queues: true
rabbitmq-backup restore --config restore-remap.yaml

Check both queues:

rabbitmqadmin list queues name messages
+-----------------+----------+
|      name       | messages |
+-----------------+----------+
| demo-queue      | 50       |
| demo-queue-copy | 50       |
+-----------------+----------+

Cleanup​

# Delete the test queue
rabbitmqadmin delete queue name=demo-queue
rabbitmqadmin delete queue name=demo-queue-copy
rabbitmqadmin delete exchange name=demo-exchange

# Remove backup data
rm -rf /tmp/rabbitmq-backups

Next Steps​