Restore Safety

Use these controls for production restores where duplicate messages, missing topology, or partial failures would be costly.

Recommended Production Restore Flow

1. Validate the backup:

rabbitmq-backup validate --path s3://rabbitmq-backups/prod --backup-id prod-2026-04-13 --deep

2. Run a dry run:

restore:
  dry_run: true

3. Dry-run definitions if you are importing topology:

restore:
  restore_definitions: true
  definitions_dry_run: true

4. Run the real restore with a checkpoint:

restore:
  dry_run: false
  definitions_dry_run: false
  checkpoint_state: /var/lib/rabbitmq-backup/prod-restore-checkpoint.db

Rollback Snapshot Before Definitions Import

When restore_definitions: true, the tool writes a target-cluster definitions snapshot before importing backed-up definitions:

{backup_id}/definitions/rollback-before-import-<timestamp>.zst

This snapshot is written after the backed-up definitions are decompressed and validated and before the import call. If the import fails, message restore does not proceed.

Selective Definitions Restore

Use definitions_selection to import only selected topology:

restore:
  restore_definitions: true
  definitions_selection:
    vhosts:
      - "production"
    queues:
      - "orders"
    exchanges:
      - "orders-exchange"

Selection rules:

Selector	Behavior
vhosts only	Restores all topology scoped to selected vhosts, including queues, exchanges, bindings, permissions, policies, and parameters.
queues	Restores selected queues and the required source exchanges and bindings that route to those queues.
exchanges	Restores selected exchanges and bindings where both endpoints are retained.
empty selection	Restores all backed-up definitions.

Invalid selectors fail before import.

Missing Target Queue Creation

For message-only restores into empty targets, use direct-to-queue publishing with queue creation:

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

restore:
  publish_mode: direct-to-queue
  restore_definitions: false
  create_missing_queues: true

create_missing_queues requires target Management API credentials. It declares missing queues using the source manifest queue type:

Manifest type	Created queue arguments
classic	{}
quorum	{"x-queue-type": "quorum"}
stream	{"x-queue-type": "stream"}

For publish_mode: exchange, restore expects exchange and binding topology to exist. Use restore_definitions: true for that mode.

Restore Checkpoints

Use checkpoint_state for long restores:

restore:
  checkpoint_state: /var/lib/rabbitmq-backup/restore-checkpoint.db

The checkpoint records processed records per queue. On rerun with the same backup_id:

• completed queues are skipped
• partial queues resume after the last checkpointed record
• failed publish batches are not marked complete

Publish Failure Handling

Restore publishes with AMQP mandatory routing. If the broker returns messages because no route exists, or publisher confirms report failures, the queue restore fails and the overall restore returns an error.

Common causes:

• target queue is missing and create_missing_queues is false
• publish_mode: exchange is used but the target exchange or binding is missing
• queue or exchange permissions do not allow publish
• target vhost mapping points to a vhost that does not exist

Use publish_mode: direct-to-queue plus create_missing_queues: true for message-only recovery into empty targets. Use restore_definitions: true for topology-aware exchange-mode recovery.