Making Node.js CMS Migration Scripts Safe to Resume

The migration has created 800 entries. Your terminal disappears halfway through the next one. The destination contains something called "About us", and your checkpoint says that record is still waiting.
Running the script again is easy. Knowing what it should do next takes a little more work.
A checkpoint describes what the importer last recorded. It doesn't necessarily describe everything the destination accepted. There is always a gap between those two writes when they belong to independent systems. I want a migration to recognise that gap, reconcile it, and stop when the evidence no longer agrees.
My example uses Node 22.20.0, a frozen source snapshot, a small HTTP destination, and a separate checkpoint file. The destination can accept a write and deliberately lose its reply. Another test kills the importer after the destination commits but before the checkpoint is saved. Neither failure is represented by a polite exception thrown before anything happened.
Decide What a Repeated Run Means
For this example, the policy is deliberately narrow: create the intended entries, verify an existing matching entry, and refuse an unexpected change. It does not update arbitrary existing content or delete anything.
Each source record has an identity which survives a restart. The migration key combines the migration name and source ID. A deterministic destination ID is derived from the same pair. The title is content, not identity; changing punctuation should not create a second record.
The plan also records the expected payload hash. Finding the right migration key is only the start of reconciliation. I still check the destination ID, content, and revision. Two entries with the same migration key are an error to investigate, not a reason to pick the first one returned by the API.
A real destination needs an appropriate uniqueness or conditional‑write mechanism. My toy service checks its in‑memory record set before persisting a create, under the documented single‑writer assumption. It is not a substitute for a database constraint across several servers.
Freeze the Source and the Mapping
Resuming from "the latest export" is asking a different question from resuming the failed run. Entries may have moved, disappeared, or changed whilst the importer was stopped.
I fingerprint the complete source snapshot together with the mapping identity. The latter includes a version label and the actual mapping file's contents. Editing the transformation therefore changes the fingerprint even if somebody forgets to update the label. An existing checkpoint must match before the importer makes destination requests.
This is intentionally conservative. Even a harmless edit to the mapping file requires a fresh review rather than quietly continuing under an old checkpoint. For a migration which is expensive to repeat, I'd rather have that conversation before another thousand records have moved.
The dry run validates the snapshot, rejects duplicate IDs, resolves dependency order, and prints the proposed operations. It creates no destination entries or checkpoint. That is useful preparation, but it cannot guarantee that the destination will still be unchanged when the real run begins.
Put Referenced Records First
The fixture deliberately lists an article before its category. The plan walks the references and schedules the category first, then writes the article with the category's deterministic destination ID.
Missing references and cycles fail during planning. A two‑pass strategy could create all identities first and attach references afterwards, but that would introduce another partial state and another recovery rule. This small example rejects cycles rather than pretending they have disappeared.
My content modelling article explains why references are part of the model, not just decoration for the editor. During migration, they also determine what can safely be written first. The final verification checks that every destination reference resolves; a count of two successful requests would not establish that.
Reconcile Before Repeating a Write
The importer looks up each migration key before attempting a create. If it finds an entry, it verifies the expected identity and content. If no entry exists, it sends the proposed write.
The awkward branch follows a failed response:
try {
current = await createEntry(operation);
} catch (error) {
current = await lookupByMigrationKey(operation.migrationKey);
if (!current) {
throw new Error('Write outcome unresolved');
}
}
verifyExpectedEntry(current, operation);This is the decision from my working example, with the HTTP plumbing removed. A successful lookup is not sufficient by itself: verifyExpectedEntry still checks the fields and revision before the importer records completion.
The lost‑reply test persists the target record, then sends an incomplete response. The importer cannot parse that reply, looks up the same key, and recognises the accepted record. Repeating the entire migration afterwards creates no additional entries. The test counts actual destination writes and inspects the stored records independently.
I covered a related ambiguity in my offline form article. Its durable operation receipt answers whether a submitted mutation was accepted. Here, the migration's stable identity and restrictive create policy allow us to reconcile a specific expected entry. Neither approach makes a network error proof that nothing happened.
Treat the Checkpoint as Evidence
My checkpoint contains the source fingerprint and a map of verified source records to destination IDs, revisions, and payload hashes. It has a checksum so accidental modification is detected before resuming. That checksum is not authentication; someone who can rewrite both the file and checksum can still alter it.
The file helper writes a new temporary file beside the destination, synchronises the file, closes it, and renames it over the previous checkpoint. The old checkpoint remains available until the replacement step. The Node file‑system API documents those operations, but their combination should not be advertised as a universal storage transaction.
This example tests process interruption on a local filesystem. It does not simulate sudden power loss, guarantee directory‑entry persistence on every filesystem, or support concurrent checkpoint writers. Those limits matter when deciding whether a local file is suitable for the real migration.
Stop When Somebody Has Changed the Target
A completed checkpoint entry does not give the importer permission to overwrite a later editorial change. The resumed run reads the target again and compares its content and revision with the recorded expectation.
My tests change a title manually, remove a previously completed target, and add an unexpected duplicate migration key. All three stop the run without issuing another create. Automatic recreation of deleted content could be just as unwelcome as overwriting an edit.
For a migration that genuinely needs updates, make the update policy explicit. Read the current record, retain fields outside the migration's ownership, and apply a version condition. Contentful's management API documentation explains its version header and rejection of stale updates. Do not copy a create‑only example into that workflow and assume a checkpoint supplies the missing concurrency control.
Prove the Restart Path
The most useful test kills the importer at a known boundary: the category has been committed, but no checkpoint exists yet. The destination stays running. A new importer process then reconciles the category and creates the remaining article. The final store has two entries, with the expected reference, and only two accepted creates across both attempts.
My migration checkpoint lab includes that scenario, the lost reply, corrupt and changed checkpoints, source and mapping changes, reference failures, and target conflicts. Its synthetic destination is deliberately separate from the importer, so a dead process cannot conveniently erase the evidence of its last write.
A resumable script needs more than a number saying how far it got. It needs a defensible answer for the record it was handling when it stopped.
Postscript
November 2026: I've checked my migration lab on Node 22.23.5 as well as the original 22.20.0 baseline. The recovery policy is unchanged: a missing acknowledgement still needs reconciliation, and a target which no longer matches the plan still needs review. My download includes the interruption tests so you can check those boundaries when adapting the importer to another CMS.