Message Schema Evolution in RabbitMQ: Using Virtual Hosts as Deployment Boundaries

Source: Dev.to

Example Scenario

Initial flow (v1)

1. The backend authorizes a payment synchronously during checkout.
2. After a successful authorization, it publishes a PaymentAuthorized event.

{
  "paymentId": "p-123",
  "authorizedAmount": 100.00,
  "currency": "EUR"
}

The consumer receives this event and captures the full authorized amount:

capture(authorizedAmount);

Evolved flow (v2)

Later, some products may be out of stock. The backend still authorizes the payment but, before capturing, checks inventory. It now publishes a PaymentCaptureRequested event that includes the actual amount to capture, which can be lower than the authorized amount.

{
  "paymentId": "p-123",
  "authorizedAmount": 100.00,
  "captureAmount": 80.00,
  "currency": "EUR"
}

The consumer should capture only the specified amount:

capture(captureAmount);

Failure Modes When Versions Co‑exist

• Missing field: If a v1 consumer receives the v2 message, the captureAmount field is unknown, causing processing errors or unpredictable behavior.
• Ignored field: A v1 consumer may ignore captureAmount and fall back to authorizedAmount, resulting in the customer being over‑charged.

The root cause is simultaneous processing of incompatible message versions.

Using RabbitMQ Virtual Hosts as Deployment Boundaries

Virtual hosts (vhosts) provide isolated namespaces within a RabbitMQ broker, allowing you to restrict communication to compatible producer/consumer pairs.

1. Externalize the vhost and credentials in Spring Boot

spring.rabbitmq.virtualHost=${RABBITMQ_VHOST}
spring.rabbitmq.username=${RABBITMQ_USER}
spring.rabbitmq.password=${RABBITMQ_PASSWORD}

2. Provision a version‑scoped vhost, user, and permissions in the pipeline

# Create a vhost for version 1.0
rabbitmqctl add_vhost payments-v1.0

# Create a dedicated user
rabbitmqctl add_user payments-v1.0-app YourStrongPassword

# (Optional) Set user tags
rabbitmqctl set_user_tags payments-v1.0-app

# Grant full permissions on the new vhost
rabbitmqctl set_permissions -p payments-v1.0 \
  payments-v1.0-app \
  ".*" ".*" ".*"

3. Pass the configuration via the container environment

environment:
  RABBITMQ_VHOST: ${RABBITMQ_VHOST}
  RABBITMQ_USER: ${RABBITMQ_USER}
  RABBITMQ_PASSWORD: ${RABBITMQ_PASSWORD}
command: java -jar ...

4. Deploy the new version

1. Deploy the updated producer and consumer pointing to the newly created vhost.
2. Run health checks to confirm all nodes are healthy.
3. Verify that messages from the previous version have been fully consumed.

5. Clean up after a successful cut‑over

• Remove the old virtual host: rabbitmqctl delete_vhost payments-v0.x.
• Delete the associated user: rabbitmqctl delete_user payments-v0.x-app.

Cleaning up prevents stale deployment boundaries from accumulating.

Further Reading

• Spring AMQP RabbitAutoConfiguration Reference – Spring AMQP Docs
• Spring AMQP Reference Documentation – Spring AMQP Docs

Cover photo by Ivan N on Unsplash