Reviewing a migration in code review
A migration is code that runs once on production and then can never change. That makes the review the last cheap
moment to catch a mistake. This page is the checklist a reviewer works through on a pull request that adds a file
to migrations/ or extension/<name>/migrations/.
What you'll have at the end
- a review that covers the file, its order, what it changes, how it is undone and where it runs;
- the commands the reviewer runs on a development installation before approving.
Before you start
Check out the branch of the pull request on a development installation with a recent copy of the site's data.
Steps
1. The file and the header
- To do: The name is
YYYYMMDDHHMMSS_name.php, the name says what it does (news_note_priority, notfix2). - To do: The file is new. A pull request that edits or renames a migration file that has run anywhere is refused: the checksum guard would stop every run there. The change belongs in a new migration.
- To do:
description:is one clear line; it appears in the status, the administration and the commit message of the run. - To do:
requires:names every migration (and kernel step, andextension:<name>) whose result this one uses. - To do:
environments:andengines:are set only when the change really is limited. Sample data never reaches production by accident: look forenvironments: development, teston it. - To do:
maintenance: yeswhere visitors must not see the change half done. - To do: One namespaced class extending
\expMigrationPhp, nothing outside the class.
2. The order
- To do: The timestamp is later than every migration already on the main branch. A branch that waited weeks may carry
an old timestamp: it then sorts before migrations that ran already, which is fine only when nothing in it
depends on them. Otherwise ask for
requires:(see Team workflow with git).
3. plan(), up() and down()
- To do:
plan()writes nothing and is cheap: it runs on every dry run and status page. - To do:
up()uses$context->db()and the run's user, never a connection or a user of its own. - To do:
up()throws on failure instead of returning quietly; return values of kernel calls are checked (createAndPublishObject(),updateAndPublishObject()returnfalseornullon failure). - To do: What
up()creates gets a remote id or an identifier, sodown()and later migrations find it on every installation. No object, node or class ids written into the file. - To do:
down()undoes exactlyup(), is safe to run twice, or is absent on purpose with a reason in the description (Writing a reversible down()). - To do: The returned messages say what was done and contain no secret, password or e-mail address.
4. Engines, transactions and size
- To do: Raw SQL works on every engine the header allows, or
engines:limits it (Engine notes). - To do: On MySQL/MariaDB and Oracle a schema change commits at once: is the order of statements the least harmful if it fails halfway?
- To do: A migration over thousands of rows uses batches and
transactional()returningfalse, and is idempotent (Large data migrations).
5. Data and privacy
- To do: No personal data of real people in the file: the file is committed and pushed. Accounts are created with placeholder addresses or read their values from settings that stay out of git.
- To do: No password, token or key in the file.
Check it
The reviewer runs, on the branch:
./console exp:migration:check
./console exp:migration:migrate
./console exp:migration:dry-run --simulate --diff # SQLite or PostgreSQL
./console exp:migration:migrate --apply --no-commit
./console exp:migration:rollback 20261101110000_news_note_priority --apply
./console exp:migration:migrate --apply --no-commitand reads the diff of the simulation: every changed table must be one the description promises.
Roll it back
A reviewer's local runs are taken back with exp:migration:rollback <migration-id> --apply, or, for a migration
without down(), with the run's caption: ./console exp:migration:rollback <run-id> --apply.
Next step
Team workflow with git: branches, conflicts and the order of migrations from several developers.
Related pages
- Migrations: the hub · All recipes
- The guide, the tutorial, PHP migrations
- In the administration, Commands, Settings
- The file format
- When a migration fails, Troubleshooting messages
- Migrations versus migrating a site
- Testing migrations, Develop with git
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.