Migrations
Rollback
Roll back a DNS migration without overwriting unrelated changes. DNSMigrator reverses only the record writes made by its own verified apply operation.
4 min read
On this page
Rollback computes a safe inverse of the operations DNSMigrator actually wrote and applies that inverse only where the current destination still matches those writes. The key point is that rollback is ownership-aware: a later human or system edit is preserved instead of being overwritten with an old snapshot.
What rollback covers#
Apply stores two pieces of rollback evidence:
- A
destination-beforesnapshot read immediately before record operations. - The successful subset of the create, update, and delete plan. Failed operations are removed from this stored subset.
Rollback reads the destination again, compares each successful operation with current state, and builds a new plan. It does not replace the whole destination with the old snapshot. This distinction prevents unrelated records and later edits from being destroyed.
Provider-managed SOA, DNSKEY, and apex NS records were never part of the migration plan, so record rollback does not touch them. It also does not delete a destination zone that apply created.
Exact inverse behavior#
| What apply did | What rollback checks | Safe inverse | When rollback leaves it alone |
|---|---|---|---|
| Created a record set | Does the current set still equal the created set? | Delete it. | It was changed after apply. If already absent, there is nothing to do. |
| Updated a record set | Does the current set still equal the applied “after” value? | Restore the pre-apply value from the snapshot. | It was changed or removed after apply. |
| Deleted a record set | Is that record-set key still absent? | Recreate the deleted set. | A record set with that key now exists. |
| Left a set unchanged | Nothing. | Nothing. | Always; it was not DNSMigrator’s write. |
| Did not know about a new set | Nothing. | Nothing. | Always; unrelated later additions remain. |
Equality includes owner name, type, TTL, normalized values, proxy state, and alias DNS target. For an update, the pre-apply snapshot is used to recover the original record even if the saved plan’s copy is incomplete.
If one or more records cannot be safely reversed, Activity reports how many “changed at provider after the migration and were left as they are.” The rest of the safe rollback plan continues.
Roll back step by step#
Check delegation first
If nameservers have already switched to the destination, use nameserver switch-back first. Record rollback removes destination answers; doing that while the domain is still delegated there can create an outage.
Stop concurrent edits
Pause automation and ask other operators not to edit the affected destination records. Later edits are preserved, but they can make the resulting zone a deliberate mix of pre-migration and current values.
Select Roll back
Open the migration and select Roll back. The dialog Roll back this migration? shows the provider and the date through which rollback is available.
Confirm the warning
The dialog reminds you to switch nameservers back first when applicable. Select Roll back again to queue the job, or Cancel to leave the destination unchanged.
Review Activity
The status changes to Rolling back and shows progress. A successful job becomes Rolled back. Review any rollback-skip warning for records preserved because they changed later.
Rollback windows#
The button is available after apply stores a rollback deadline and before rollbackUntil:
| Entitlement used for apply | Window stored after successful apply |
|---|---|
| Migrate | 7 days |
| Migrate + cutover | 30 days |
| Automated | 30 days |
| Agency’s included guided-cutover tier | 30 days |
A higher entitlement controls the longer window even when the record count itself required only Migrate. A partial apply failure stores the Migrate window for the successful subset. After the timestamp passes, the service refuses rollback and the Roll back button is hidden.
These windows are part of the current offers in Plans and billing and Pricing. They are not DNS cache timings; delegation and DNSSEC caches have separate safety requirements.
Failures and retries#
Rollback uses the destination connection and provider API. If reading the zone or applying an inverse operation fails, the migration becomes Needs attention and the error appears in Activity. Successful inverse operations are not automatically replayed from scratch as a whole-zone restore.
Before retrying, read the live destination and the event log. Do not manually force old values over records that the safe algorithm skipped unless you know why those records changed. For a file-level comparison, export the relevant zones and use the zone diff tool or npx dnsmigrator diff from the CLI.
What rollback does not restore#
Rollback intentionally does not:
- Change registrar nameservers or DS records.
- Restore TTLs lowered on the source during cutover.
- Disable DNSSEC enabled at the destination.
- Recreate or delete the destination zone container.
- Change the source zone.
- Overwrite a destination record edited after apply.
A completed cutover therefore needs a coordinated switch-back plan, especially when DNSSEC has been re-enabled. Read DNSSEC transitions before reverting a signed delegation.
Verify the result#
After Rolled back, inspect Activity for skipped records and query the destination if it will continue serving traffic during cached delegation. If you switched nameservers back, use the propagation checker to see which resolvers still use each provider. Keep both zones able to answer during that overlap; How to migrate DNS without downtime explains why.