RabbitMQ / Advanced: ordered ownership, retained replay and accepted recovery / Lesson 17
Topology migration and upgrades
Plan compatibility and message coverage across topology or version changes without treating declaration errors as permission to delete data.
On this page
Lesson goals
- Review immutable queue properties and staged migration boundaries.
- Separate binary, Erlang, feature-flag and application compatibility.
An existing queue name carries a contract
Redeclaring a queue with incompatible durability, type or other equivalence-sensitive properties can fail with PRECONDITION_FAILED. That error identifies a mismatch, not permission to delete the populated resource. Determine which application owns the declaration and which consumers depend on it. A queue-type change generally needs a planned new topology and message/application migration rather than an in-place policy edit. The destination contract should preserve business identity and required ordering across old and new paths. Include dead-letter routes, reply queues and permissions in the inventory so a seemingly small rename does not disconnect an overlooked processing stage.
An upgrade is more than replacing one package
RabbitMQ version transitions depend on supported upgrade paths, compatible Erlang versions, enabled feature flags, plugins and client behavior. Review exact source and target releases rather than assuming any two 4.x versions can be mixed arbitrarily. Feature enablement can change rollback options independently from binary replacement. Classic queue mirroring is absent in 4.x, so legacy high-availability settings do not recreate that feature. Managed products can constrain upgrade sequence and available plugins. This course selects 4.1 documentation for teaching and makes no latest-release or support claim; operational decisions need the current official compatibility matrix for the actual deployment.
Define cutover coverage before moving traffic
The JSON plan names old and new queues, a finite source range and stable operation identity. It is a design artifact, not an instruction to copy messages, alter bindings or perform an upgrade. A migration must decide when publishers switch, how old backlog drains and how duplicate deliveries from overlapping paths are recognized. Counts alone can hide both duplicates and omissions, so compare unique identities and expected business results. If strict key order matters, simultaneous old/new consumers can violate it unless the transition explicitly coordinates ownership. Record a stopping and rollback boundary that reviewers can evaluate before any authorized execution.
{"source_queue":"lab.labels.v1","destination_queue":"lab.labels.v2","required_operations":["evt-a","evt-b","evt-c"],"identity_policy":"preserve-original","cutover":"reviewed-publisher-boundary","rollback":"review-before-execution"}The plan records review requirements and performs no binding change, drain or message transfer.
Compare required identities with accepted destinations
The local sets contain three required operations and only two accepted destination identities. The difference identifies evt-b as missing in that fixture. This is coverage arithmetic, not a queue drain, transfer protocol or proof of live message absence. A real acceptance review also needs conflicting payloads, duplicated identities and destination effect state. A definitions export preserves topology metadata rather than queued message bodies, so it cannot alone restore a drained or lost backlog. Backup/restore procedures have node-identity and consistency restrictions that must follow the official version-specific guide; copying a running data directory is not a validated recovery strategy here.
required = {'evt-a', 'evt-b', 'evt-c'}
accepted_destination = {'evt-a', 'evt-c'}
missing = required - accepted_destination
assert missing == {'evt-b'}
print(sorted(missing))['evt-b']evt-b is missing from the supplied destination set; no broker state is inspected.
Keep service health and business acceptance separate
After a separately authorized change, useful verification includes routing, confirms, consumer acknowledgments, queue availability and accepted business effects. A successful process restart or a green cluster overview is not complete acceptance. Retain original versions, effective policies and coverage evidence while evaluating rollback. A package downgrade does not automatically reverse metadata, feature or external-effect changes. This lesson runs no upgrade, migration, export, restart or administrative command. It parses a plan and executes set comparison only, leaving actual mixed-version compatibility, recovery timing and rollback safety explicitly untested rather than implied by the small model.
Common errors and fixes
A declaration mismatch is fixed by deleting a populated queue immediately.
- Why it happens
- Compatibility diagnosis was replaced by destructive recreation.
- How to fix it
- Identify ownership and prepare a message-coverage migration plan.
- Prevent it next time
- Review immutable properties before client rollout.
Definitions export is treated as a full message backup.
- Why it happens
- Topology metadata was confused with message bodies.
- How to fix it
- Inventory recovery data types and use supported procedures.
- Prevent it next time
- Test business backlog recovery separately from topology restore.
An arbitrary package downgrade is assumed to undo an upgrade.
- Why it happens
- Feature and metadata rollback constraints were omitted.
- How to fix it
- Follow exact supported source/target and recovery guidance.
- Prevent it next time
- Record rollback boundaries before enabling new features.
Check your understanding
1. Why is matching total message count insufficient proof of migration coverage?
Show worked solution
A duplicate can replace a missing operation while leaving the same total. Compare required unique identities, payload consistency and accepted destination effects. Preserve a declared source boundary and explicitly account for overlap so a convincing count does not hide omitted or repeated business work.
2. Does the missing-set assertion certify a live queue has lost evt-b?
Show worked solution
No. It compares supplied synthetic sets only. A live investigation requires authorized source/destination evidence, timing and handling of in-flight work. The fixture teaches the acceptance invariant without querying a broker or claiming a message transfer, loss diagnosis or safe operational rollback was performed.
Key takeaways
- Version and topology changes require explicit coverage and compatibility plans.
- A restore or rollback claim must include message and business-state evidence.