Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Reviewing a migration in code review

A checklist for reviewing a migration in a pull request - the file and header, the order, plan(), up() and down(), engines and transactions, ids that differ between installations, personal data, and what the reviewer…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/migrations/recipes/reviewing-a-migration.md

On this page

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, not fix2).
  • 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, and extension:<name>) whose result this one uses.
  • To do: environments: and engines: are set only when the change really is limited. Sample data never reaches production by accident: look for environments: development, test on it.
  • To do: maintenance: yes where 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() return false or null on failure).
  • To do: What up() creates gets a remote id or an identifier, so down() and later migrations find it on every installation. No object, node or class ids written into the file.
  • To do: down() undoes exactly up(), 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() returning false, 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-commit

and 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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x