Migration settings
The settings of migrations are in settings/migration.ini. Never edit that file: an update replaces it. Put what you
change in an override:
settings/override/migration.ini.append.phpfor the installation,settings/siteaccess/<siteaccess>/migration.ini.append.phpfor one siteaccess,extension/<extension>/settings/migration.ini.append.phpin an extension (read while the extension is active).
# settings/override/migration.ini.append.php on a development installation
[RepositorySettings]
Push=disabled
*/ ?>Contents
migration.ini
| Block and setting | Default | What it does |
|---|---|---|
| [MigrationSettings] (reference) | where migrations are found | |
Enabled | enabled | disabled finds no migrations at all |
DirectoryList[] | migrations | the site's migration folders; the first is where exp:migration:generate writes |
ExtensionDirectory | migrations | the folder inside every active extension and every installed package |
| [RunSettings] (reference) | how a run behaves | |
RunAsUser | admin | the login a console run runs as (a run in the administration runs as the signed-in user) |
StopOnFailure | enabled | stop at the first failure; disabled goes on with migrations that do not require the failed one |
Throttle | empty | shipped empty; the 6.0.15 runner does not read it (pause inside a long migration yourself, see Large data migrations) |
| [CaptionSettings] (reference) | the safe points around a run | |
Before | enabled | a caption (kind migration-pre) before every run |
After | enabled | a caption (kind migration-post) after a run that passed |
ReuseUnchanged | enabled | reuse the newest caption while nothing has changed since |
ReuseIgnoreTableList[] | exp_migration, exp_migration_run, expupgrade_step, ezsession, expaudit_* | tables the reuse check leaves out |
RestoreOnFailure | enabled | restore the pre caption after a failure |
RestoreParts[] | database, storage, settings | the parts of a caption that restore puts back |
CodeTreeList[] | settings, extension, design | trees checked for uncommitted changes before --apply |
BackupDirectory | empty (var/backup/upgrade) | where captions made without git_manager are kept |
| [RepositorySettings] (reference) | the record in git | |
Mode | site | site: the installation's own checkout; separate: a repository of its own at Path |
Path | migrations | the folder of the status files and run logs |
Remote | origin | the remote to push to; empty: no push |
Branch | empty | the branch to commit on; empty: the current one |
Commit, Tag, Push | enabled | commit the record, tag the commit, push both |
TagPattern | migrations/<environment>/<run-id> | the tag name; placeholders <environment>, <run-id>, <date> |
| [AdminSettings] (reference) | runs started in Setup > Migrations | |
PhpCliPath | empty | the PHP command line binary that runs them in the background |
JobHistory | 50 | how many runs keep their files in var/<site>/migration/jobs/ |
LogBytes | 262144 | how much of the end of a run log a page shows |
Every setting with its full comment: the blocks of migration.ini.
An extension can point ExtensionDirectory elsewhere:
the extension points of migration.ini.
Settings in other files
| File and block | Setting | For migrations |
|---|---|---|
site.ini [AdminEnvironment] (reference) | Level | the environment of the installation (development, test, staging, production; auto reads EXP_ENV), which the header line environments: and the status file name use |
site.ini [ReauthGroup_system] (reference) | "Verify it's you" before a run, a resume, a simulation and a rollback in the administration | |
dashboard.ini [DashboardBlock_migrations] (reference) | PolicyList[] | the dashboard block, for users with migration/read |
audit.ini [AuditEventSettings] (reference) | Enabled[] | the audit events system.migration.run, .apply, .fail, .rollback, .caption, .push |
cronjob.ini [CronjobPart-migrationpush] (reference) | Scripts[] | the part that pushes runs whose push failed (the cronjob part) |
upgrade.ini [UpgradeSettings] (reference) | ExtensionStepList[] | an extension's upgrade steps, which are listed among the migrations as source kernel |
Typical settings per environment
| Development | Staging | Production | |
|---|---|---|---|
[AdminEnvironment] Level | development | staging | production |
[RepositorySettings] Push | disabled (or --no-push) | enabled | enabled |
[CaptionSettings] Before, After | enabled (cheap on SQLite) | enabled | enabled |
[CaptionSettings] RestoreOnFailure | enabled | enabled | enabled |
[RunSettings] RunAsUser | admin | a dedicated administrator login | a dedicated administrator login |
A setting that differs per environment goes in the environment's own override (for example the variant files of
EXP_ENV, settings/override/site.ini.prod.append.php), never in a migration: migrations are the same files on every
installation (Per-environment migrations).
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, Commands, Policies, views and events
- The file format, The feature
- When a migration fails, Troubleshooting messages
- Migrations versus migrating a site
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.