Migration commands #
The migration commands run from the installation root as ./console exp:migration:<name> (the same program as
php bin/php/expmigration<name>.php). Run them as the user the web server runs as; as root, add --allow-root-user.
Every command that writes is a dry run until it is given --apply. Each command's full list of options is on
its generated reference page, made from the command's own option definitions.
Contents #
- The commands
- By task
- Options most commands share
- Exit codes and the machine output
- The exp:upgrade commands that work with migrations
- Related pages
The commands #
| Command | What it does | Most used options | Reference |
|---|
exp:migration:status | every migration with its state (done, pending, not-needed, failed, unknown), the orphans, the latest runs, the pushes that wait, the lock | --fail-on-pending, --runs, --environment | expmigrationstatus |
exp:migration:migrate | the dry run, and with --apply the run: caption, migrations in order, restore on failure, re-caption, commit, tag, push | --apply, --only, --path, --environment, --login, --no-commit, --no-push, --force --reason | expmigrationmigrate |
exp:migration:dry-run | the plan of every pending migration; --simulate runs them in a transaction that is rolled back (PostgreSQL, SQLite), --diff shows what changed | --simulate, --diff, --only, --path | expmigrationdryrun |
exp:migration:rollback | takes back a run (its pre caption), one migration (its down()), or, for experts, any caption | <run-id>, <migration-id>, --expert --confirm=<caption-id>, --parts | expmigrationrollback |
exp:migration:resume | a new run of what a failed or interrupted run left pending | --apply, --only | expmigrationresume |
exp:migration:caption | a caption of the installation now, or the list of captions | --apply, --list, --label | expmigrationcaption |
exp:migration:push | pushes the runs whose push failed | --apply, --limit | expmigrationpush |
exp:migration:check | the lint of the migration files, without a database: names, headers, order, PHP syntax, the class | --path, --environment | expmigrationcheck |
exp:migration:generate | writes a new PHP migration from the skeleton | --skeleton <name>, --description, --author, --source=extension:<name>, --apply | expmigrationgenerate |
exp:migration:convert | converts YAML migrations of the reference bundle into YAML migrations of Exponential; what does not convert is listed in the new file | <file or folder>, --source=extension:<name>, --apply | expmigrationconvert |
exp:migration:repo:split | splits the migrations folder into a repository of its own, with its history | --to, --remote, --branch, --apply | expmigrationreposplit |
By task #
Options most commands share #
| Option | Meaning |
|---|
--apply | make the changes; without it, a dry run that changes nothing |
--format=json | the machine output exp-migration/1 instead of text |
--environment=<name> | count the migrations for another environment than the installation's (site.ini [AdminEnvironment] Level, or EXP_ENV with Level=auto) |
--login=<login> | run as this user instead of migration.ini [RunSettings] RunAsUser |
--only=<ids> | only these migrations (a comma list or repeated) |
--path=<files or folders> | only the migrations in these files or folders; exp:migration:check checks them instead of the migration folders |
--run-id=<id>, --progress=<file> | name the run before it starts, and follow it through a file of JSON lines (what the administration uses) |
Every script also takes the standard options of the script framework (--help, --siteaccess, --debug,
--quiet, --allow-root-user).
Exit codes and the machine output #
| Code | Means |
|---|
| 0 | done, or nothing to do |
| 1 | a migration failed, a check found a problem, the lock was held, a changed file was refused, or something is pending with exp:migration:status --fail-on-pending |
| 2 | usage: an option is wrong or missing, or uncommitted code refused a run |
| 3 | the database is not reachable |
| 4 | internal error |
--format=json writes exp-migration/1: the run, the environment, the engine and its transaction mode, every
migration with its state, action and messages, the captions, the repository, a summary, the errors, the warnings and
the exit code (The machine output).
./console exp:migration:status --fail-on-pending --format=json > var/log/migration-status.json || echo "pending or failed"
The exp:upgrade commands that work with migrations #
The kernel's upgrade steps are migrations of the source kernel, and exp:upgrade shares the record, the lock and
the captions with the migrations:
| Command | With migrations |
|---|
exp:upgrade | creates the record tables (step 6.0.15-migration-tables); runs every stage, also code, libraries and finish, which a migration run leaves to it |
exp:upgrade:status | the steps and their state; a step applied by a migration run is done here too |
exp:upgrade:captions | lists the captions of upgrades and of migration runs (kinds migration-pre, migration-post, migration-failure) |
exp:upgrade:rollback | restores any caption, also one a migration run took |
exp:upgrade:finish | after a migration run that applied steps, or after a restore: deploy, caches, smoke check |
exp:upgrade:verify | finds drift: a step recorded done whose effect is missing |
Related pages #
- Migrations: the hub, All recipes, Frequently asked questions
- The guide, the tutorial,
PHP migrations,
Rollback and captions,
The migrations repository
- In the administration, Settings,
Policies, views and events
- The file format,
The feature
- When a migration fails,
Troubleshooting messages
- Migrations versus migrating a site
- All console commands, Upgrading with the console
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.