Migrations
Bulk migrations
Plan bulk DNS migrations from CSV, validate every row, create previews, track per-zone progress, and understand limits before applying changes at scale.
5 min read
On this page
Bulk import validates a CSV and creates one ordinary migration preview for each valid zone, using connection names already in the workspace. The key point is that bulk import does not apply or cut over anything: every generated migration still opens with its own record preview, plan, verification, and cutover controls.
Requirements#
Open Bulk import from the app navigation. You must be a workspace administrator to check or start rows. Check rows is available without the bulk entitlement, but Start previews requires an active Agency workspace plan.
Agency includes the guided-cutover migration tier. Generated migrations can therefore apply any number of translated target record sets and use I’ll switch it while the subscription remains eligible. We switch it still requires an Automated entitlement for that zone. See Plans and billing and Nameserver cutover.
Use an active DNS provider connection for each source; a pasted BIND file cannot be a bulk source. Destinations can be active connections or the special zonefile value. A connected destination needs write scope only when you later apply its migration.
Prepare the CSV#
Use the canonical header shown by Use the template:
zone,source,destination
example.com,AWS production,Cloudflare production
example.org,AWS production,zonefile
"example.net","Source, client A","Destination, client A"| Column | Value |
|---|---|
zone | A valid domain present in the selected source account. A trailing dot is accepted and removed for matching. |
source | A connection label from this workspace. Connection IDs also resolve, but labels are easier to audit. |
destination | Another connection label, or zonefile / zone file for an offline export. |
Header names are case-insensitive. The parser also recognizes domain for zone, from for source, and dest or to for destination. Without a recognized header, the first three columns are interpreted positionally as zone, source, and destination.
Standard CSV quoting is supported: commas can appear inside double quotes, and a literal double quote is written as "". Fields are trimmed. Empty rows are ignored.
The web action accepts up to 500,000 characters of CSV text, and the service accepts up to 500 data rows per import. If a recognized header exists, it is not counted as a data row.
Validate and start previews#
Paste or open the CSV
Select Open CSV to read a local .csv file, select Use the template, or paste text into CSV with one zone per row. Editing the text clears the last validation result.
Select Check rows
DNSMigrator parses the file and resolves connection labels inside the current workspace. No provider zones are read and no migration is created at this point.
Fix rows with problems
The Rows panel shows _ready_ · _with problems_. Correct invalid domains, missing or inactive connections, and same-connection pairs, then select Check rows again. Check destination write scope separately under Connections.
Select Start previews
The button changes to Start n previews when at least one row is ready. Invalid rows stay skipped; valid rows are queued in one bulk job.
Open each migration
The worker processes rows, lists each source account’s zones, matches the requested name, and calls the normal migration creation flow. Review each result under Migrations before applying.
Row validation#
| Condition | Result shown for the row |
|---|---|
| Domain syntax is invalid | Not a valid domain. |
| Source or destination label is unknown | No connection named “…” |
| A connection is not active | Connection “…” isn’t active. |
| Source and destination resolve to the same connection | Source and destination are the same connection. |
| Destination credential lacks write scope | The row can still be Ready; preview can succeed, but a later apply can fail. |
Destination is zonefile | Ready, provided the source connection and domain are valid. |
A provider can have read-only credentials even when the provider type itself supports writes. The row validator checks only that each connection is active and that source and destination are different; it does not inspect credential scopes or provider-level read-only capability. Check for Read + write under Connecting providers before applying.
What the bulk worker creates#
Rows run sequentially inside the bulk job. Source zone lists are cached per connection for that run. For each valid row, the worker:
- Finds the exact zone name in the source account, ignoring case and a trailing dot.
- Creates a migration with the source zone reference and chosen destination.
- Uses the default Keep extra records mode.
- Queues the normal free preview.
- Stores the migration ID on the row, or a short error if creation failed.
It does not change mode to Make an exact copy, buy a per-zone Automated tier, apply records, verify, or start cutover. Adjust and approve those operations inside each migration. Read Migration workflow and Previews and record statuses.
A zonefile destination creates a preview whose final action is Download zone file. Downloads are per migration; the bulk job does not produce one archive.
Monitor recent imports#
Recent imports refreshes while a job is queued or running. Each row shows its job status and _created_ · _skipped_ counts:
queued: waiting for the worker.running: source zones are being resolved and migrations created.done: every row was either linked to a migration or given an error.failed: reserved by the stored job model; row-level failures normally produce a completed job with skipped rows.
The service keeps the 50 most recent bulk jobs in this view. A done job does not mean its migration previews have finished; open Migrations and wait for each one to reach Ready to review or Needs attention.
Operational practices#
Use distinctive connection labels before preparing the CSV, especially when one provider has several accounts. Start with a small batch, inspect translation results, and only then submit the larger set. Provider feature losses often repeat across a pair, but apex aliases, mail records, and routing policies still need per-zone review.
For offline inventory, choose zonefile and inspect each output with the zone-file validator. For post-apply delegation work, use the same DNSSEC transition and cutover checks as a single migration.