{"canonical_url":"https://engineer.company/glossary/migration/","content_markdown":"# Migration\n\n## What it is\n\nA migration is a planned move of something already in use to a new version or\nplatform, carried out in steps, with the old one retired at the end. The thing\nbeing moved can be a whole workload, an application, a body of data or the\nstructure that data is kept in. What separates a migration from a rebuild is\nthat the system stays in use while it moves: its users, records and integrations\ncome along, and the old version keeps working until the new one has taken over.\n\nEngineers use the word at two scales, often without saying which one they mean.\n\nAt the large scale it is a move to a new platform or a new major version.\nMicrosoft's Cloud Adoption Framework treats moving workloads to Azure, from\nservers on premises or from another cloud, as five steps: plan, prepare the\nworkloads, execute, optimise, and decommission the source. Esri's customers move\ntheir maps and data from ArcMap to ArcGIS Pro. A Next.js application moves from\nthe Pages Router to the App Router, and `getServerSideProps` gives way to\nfetching data inside Server Components. A PostgreSQL cluster moves to a new\nmajor version, which often changes the layout of the system tables, so the data\nis carried across with `pg_upgrade` or with a dump and restore.\n\nAt the small scale a migration is one versioned change to a database's\nstructure, kept as a file in the repository and applied by a tool in a fixed\norder. Django calls its migrations a version control system for the database\nschema: each file records a change to the models, is committed with the code,\nand runs in the same sequence on a developer's laptop, on staging and in\nproduction. GitLab ships batched background migrations that rewrite large tables\na batch at a time after an upgrade, for example widening integer columns to\n`bigint` before they overflow. A data migration belongs here too: one that\nchanges the rows rather than the columns, such as filling a new field from two\nold ones.\n\nThese are one idea at two scales. Each has a known starting state, an ordered\nset of steps, a target, and a way back if a step goes wrong. A platform move\nusually contains schema migrations, and a long run of schema migrations is, over\nthe years, a platform changing piece by piece under the people who use it.\n\n## Why it matters\n\nSoftware outlives what it was built on. Cloud contracts are renegotiated,\nframeworks change their model, and vendors retire products. A system kept for a\ndecade will be migrated several times in that decade, so how well a team\nmigrates ends up mattering more than how well it chose the first platform.\n\n1. **The split state is where the cost lands.** While part of a system runs on\n   the old platform and part on the new, both have to be operated, monitored and\n   kept consistent. The Cloud Adoption Framework tells teams to keep that period\n   short and to move components that depend directly on each other in the same\n   wave.\n2. **A database cannot be redeployed.** Code can be built again and replaced;\n   the rows in production cannot. Schema migrations turn a change to live\n   structure into a file that can be reviewed, tested against a copy, applied in\n   order and, for most changes, reversed. The alternative is a production schema\n   that is whatever the last person with a console left behind.\n3. **A planned move can be undone.** The Cloud Adoption Framework asks for\n   rollback criteria and procedures to be set before any migration starts, for\n   the rollback to be tested, and for go/no-go checkpoints along the way.\n\nThe trade-offs sit in the cutover. The Cloud Adoption Framework separates\nmigration with downtime from migration with near-zero downtime, where data is\nreplicated continuously and the switch comes at the end. For a major version of\nPostgreSQL, `pg_upgrade` shortens the cutover: it skips the dump and restore such\nan upgrade typically requires by reusing the existing data files, and in\n`--link` mode, which copies no files, it is much faster again.\n\n## What it looks like in practice\n\nThree projects on this site show the term at three sizes, from a whole platform\ndown to the order of the files in one repository.\n\nOne migration was a move off a cloud provider. A client's AWS setup had been\nover-provisioned, and the work began by reviewing what was really used:\nunnecessary services went, and the remaining capacity was adjusted.\nThe workloads then\n[left AWS](/portfolio/a-tenth-of-the-cloud-bill-and-nothing-lost/).\nThe engagement record supports those infrastructure changes. Cutting unused\nservices before moving meant there was less to carry; it does not establish a\nlike-for-like cost ratio, a productivity result or a disruption-free migration.\n\nThe second was an engine change with a new design at the far end. A geographic\nmap application's database moved from MSSQL to PostgreSQL with the PostGIS\nextension, and the target was not a copy of the old structure.\n[The new schema was designed for spatial data](/portfolio/improved-gis-map-performance-10x-on-postgresql/),\nwith GiST and SP-GiST indexes and strict foreign key and check constraints that\nenforce validation rules on spatial coordinates. Over 50 million spatial records\ntravelled into it through ETL pipelines that transformed them to EPSG:4326. A\nmove onto a new design is the chance to state the data's rules in the schema\nitself. The page reports a 10x improvement in spatial query performance and\nbackend CPU load down by 65%.\n\nThe third is the small scale, kept up for years. One platform's schema is the\nsum of\n[1,022 migrations, numbered 036 through 1102](/portfolio/1022-migrations-behind-a-schema-drift-gate/),\nand the page calls the ordering discipline around them unglamorous and\nnon-negotiable. The history in the repository is a description of production,\nand it stays true only while any database, from a developer's fresh copy to a\nrestore, can be rebuilt by replaying it from the first file to the last.\n\n## Where it goes wrong\n\nThe cutover gets the planning, and the trouble tends to gather in the weeks\naround it, in four recognisable shapes.\n\n**Two systems run side by side for longer than planned.** The move stalls\nhalfway, the pieces left are the hard ones, and the team runs both platforms for\nmonths. Users feel the seam: the Next.js guide notes that moving between a Pages\nRouter page and an App Router page is a hard navigation, and that `next/link`\ndoes not prefetch across the two. Keep the waves small and make each next step\ncheap. One frontend here moves its pages onto\n[a shared factory that loads each page in one round trip](/portfolio/built-the-next-js-16-frontend-ssr-ssg-and-csr/),\nso every converted page inherits the behaviour.\n\n**A cutover with no way back.** Some steps change the source as well as the\ntarget. With `pg_upgrade --link`, once the new cluster has started it has\nwritten to files the old one shares, and the old cluster then has to be restored\nfrom backup. Esri warns that a dataset upgraded for ArcGIS Pro may stop being\nusable in ArcMap, and tells users to copy it first. In Django, a `RunSQL`\noperation written without reverse SQL raises `IrreversibleError` the moment\nsomeone migrates backwards. Set the rollback criteria before the first step,\nrehearse the route back, and turn it into a check: one repository here runs a\nguard engine whose validators include\n[a check that a migration can be rolled back](/portfolio/built-a-268-check-guard-engine-for-the-repo/).\n\n**A migration that already ran gets edited.** Migration tools record which files\nhave been applied and skip them from then on. Change a file after it has reached\nproduction, and production keeps the old version while every fresh database gets\nthe new one: two schemas under one history. Leave applied migrations alone and\ncorrect them with a new one; a build that replays the history from empty and\ncompares it with a migrated copy catches the drift.\n\n**The upgraded database is slow on its first day.** `pg_upgrade` carries most\nplanner statistics across, not all, and the planner guesses on the rest until\nthey are rebuilt. Its `--check` mode changes nothing and can run while the old\nserver is still serving, so run it first, and rebuild the missing statistics\nstraight after the upgrade before gathering the rest:\n\n```sh\npg_upgrade --check -b \"$OLD/bin\" -B \"$NEW/bin\" -d \"$OLD/data\" -D \"$NEW/data\"\npg_upgrade -b \"$OLD/bin\" -B \"$NEW/bin\" -d \"$OLD/data\" -D \"$NEW/data\"\nvacuumdb --all --analyze-in-stages --missing-stats-only\nvacuumdb --all --analyze-only\n```\n\n## Further reading\n\n- [Plan your migration](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/migrate/)\n  — Microsoft's method for moving workloads to Azure: waves, cutover choices and\n  rollback planning.\n- [Migrations](https://docs.djangoproject.com/en/stable/topics/migrations/) —\n  Django's guide to versioned schema changes, reversing them and data\n  migrations.\n- [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html) — the\n  PostgreSQL upgrade tool, with check mode, link mode, reverting and the\n  statistics steps afterwards.\n- [How to migrate from Pages to the App Router](https://nextjs.org/docs/app/guides/migrating/app-router-migration)\n  — moving a Next.js application to the new router one page at a time.\n- [Migrate existing work](https://doc.esri.com/en/arcgis-pro/latest/get-started/migrate-existing-work.html)\n  — what carries over from ArcMap to ArcGIS Pro, what has to be converted, and\n  what to back up first.\n- [Check migrations before upgrade](https://docs.gitlab.com/update/background_migrations/)\n  — how GitLab's batched background migrations rewrite large tables after an\n  upgrade, and how to see that they have finished.\n\n\u003chttps://engineer.company/glossary/migration/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"What a migration is, from moving a whole platform to one ordered schema change, why each needs a way back, and four ways the move goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/migration/index.gmi","gopher":"https://engineer.company/glossary/migration/gophermap","html":"https://engineer.company/glossary/migration/","json":"https://engineer.company/glossary/migration/index.json","markdown":"https://engineer.company/glossary/migration/index.md","pdf":"https://engineer.company/glossary/migration/index.pdf"},"kind":"page","language":"en","title":"What is a migration?","url":"https://engineer.company/glossary/migration/","version":1}