← All articles
Foundations Article 1 of 4

Migratly: what it is

One engine, and a written description for each system it connects. What the product does, and what it deliberately doesn't.

8 August 2026 · 4 min read

A migration usually looks fine right up until someone opens a record.

The counts match. Then someone opens a record they remember creating, and the link that pointed at a related document is plain text. The custom field carrying the one piece of context nobody else tracked is absent - not empty, absent. Records that lived inside a parent are sitting at the top level, as though they had never belonged to anything. The attachment is a filename with nothing behind it. The migration reported success, because from the tool's point of view it succeeded: it moved every record it knew how to move, and silently skipped the rest.

That gap - between the records arrived and the work survived - is what Migratly exists to close.

What Migratly is

Migratly is a migration engine in which a new source-to-target pair is a description rather than a codebase.

There is one engine. It knows about generic things - collections, records, schema definitions, content, relationships between records. It does not know what any particular product is. Each system is described separately: how to authenticate, how it paginates, what entities it has, how records are constructed in it, how references inside content behave. Adding a system means writing that description. Adding a pair means having both descriptions and a mapping between them.

Source Your current system Read-only. Never written to.
Connector description Auth · pagination · entities · how records are read
Migration engine
01Schema discovery
02Mapping & coverage
03Execution in dependency waves
04Reference resolution
05Verification
One engine, every pair. It understands collections, records, schema, content and relationships - never a specific product.
Connector description How records are built · how references resolve
Target Your new system Written once, idempotently
Audit & state Every action recorded, append-only. A run resumes where it stopped; running it twice doesn't duplicate.
Agents Propose the field mapping, draft the description of a new system, run parity checks. They advise - they don't execute.
The engine is fixed. Everything product-specific lives in the two connector descriptions on either side of it.

The five things it does

01It describes systems instead of programming them

A connector is a document, not a component. That's what makes the second migration between the same two tools cost delivery time and nothing else - and what makes a pair nobody has built yet a writing task rather than a project.

02It tells you what won't survive, before it runs

Every field in the proposed mapping is classified: fully supported, partially supported, supported through a workaround, impossible in the target, or needing a human decision. Anything that isn't fully supported is surfaced for explicit confirmation with a plain-English reason.

Loss is sometimes unavoidable - the target genuinely may have nowhere to put a field. Silent loss is a choice, and we made the other one.

03It handles references between records

This is the part that breaks free importers. References form cycles, point at records that don't exist yet, cross container boundaries, and - awkwardly - cross migrations. Migratly holds the ones it can't resolve yet and drains them in a later pass, repeatedly, until nothing new resolves.

That survives an interrupted run, and it survives across separate runs: migrate one batch in July and another in October, and the first batch's dangling links start working when the second lands.

04It can be stopped and restarted

A run resumes from where it stopped rather than from the beginning. Running the same migration twice doesn't duplicate anything. A record that fails is isolated and logged, and the run keeps going, rather than one bad row ending the night. Every action is recorded in a history that is only ever appended to.

The same properties make a later run from a new starting point possible. Migrate now, keep working in the source for another month, then run again from that point - what already moved is recognised and left alone, and only what changed or was added since comes across. A cutover does not have to happen in one night, and it does not have to happen before you are ready.

05It checks its own work

After a run, records are sampled from both systems and compared field by field, producing a discrepancy report and proposed corrections that a person approves or rejects. This is the difference between believing a migration worked and being able to sign off on it.

Threaded through all five: AI proposes, the engine executes. Agents read both schemas and draft the field-level mapping, draft the description of a system nobody has connected before, run the parity comparison, and hold per-field comment threads during review. The migration itself doesn't improvise. An agent that suggests a mapping is useful and reviewable; an agent that is the migration can't be audited, and nobody signs off on a system they can't audit.

What it deliberately doesn't do

Next in this series: what actually happens during a migration, start to finish - connecting both systems, reviewing the coverage report, and what "dependency waves" means when you're watching one run.

See the coverage report before anything is written

Connect a source and a target, and read exactly which fields survive intact, which arrive diminished, and which the target can't represent at all - before a single record moves.