---
name: migration-cutover
description: Rehearse broker state handling, traffic movement and rollback for a CitusIO replacement while preserving one writer and reconciling external effects.
---

# Cut over and roll back a broker

Read [the private case workflow](../references/migration-workflow.md) and
[state policy](../references/state-policy.md). Begin with validated mappings,
exact identities, traffic evidence and existing authorization. Unresolved
semantics, unknown state, failed drain or missing ownership block live movement;
continue independent preparation.

1. Preserve source configuration and a verified recovery point. Record retained,
   session/offline/in-flight state, bridge/sink frontiers, pause/drain bounds,
   canary scope, observation window and rollback triggers.
2. Quiesce publishers and side effects. Drain or apply the explicit state policy;
   timeout does not permit loss. Database files, sessions and packet IDs are
   not automatically portable.
3. Fence the old writer. Route only when
   `node_ready && shard_ready && owns_current_writer_term` holds. Reconnect a
   canary; verify auth, ACL, exact delivery and effects before expanding traffic.
4. Rehearse failure before movement and after target writes. After advancement,
   fence/quiesce the target, reconcile retained updates/deletes, queues and
   completed/ambiguous sink effects, then restore source ownership/readiness
   before returning traffic.

Prefer source drain, retained reseed/reconciliation and reconnect/resubscription
where supported. Remaining TTL must not restart silently. Same-broker recovery
is distinct from cross-broker import. Overlap needs proved loop prevention and
one side-effect owner. MQTT packet IDs/DUP/QoS do not deduplicate external
effects; record stable IDs, raw receipts and application idempotency separately.

Keep attempts, final owner, reconciliation and the next action in the case.
Clean up only recorded owned resources. Separate rehearsal completion from
authorized live customer migration.