Migrations
A migration is a change to an installation (a table, a column, a content class, content, a role, a setting) written once in a PHP file under version control and applied to every installation of the site (development, staging, production) in the same order. Exponential 6.0.15 runs migrations in the kernel: it records what ran where, takes a caption (a safe point) before every run, restores it automatically when a migration fails, and commits, tags and pushes the record of every run.
Looking for something else? Moving a site to another server, upgrading it to a new release or bringing content in from another system is migrating a site, a different job with its own pages: Migrations versus migrating a site.
Contents
- Start here
- Who it is for
- Recipes
- In the administration
- Reference
- When something goes wrong
- YAML migrations
- What 6.0.15 has, and what comes later
- Related pages
Start here
| You want to ... | Start with | Then |
|---|---|---|
| write your first migration (about 20 minutes) | the tutorial | PHP migrations, the recipes |
| understand what migrations are and how a run works | the guide | Rollback and captions, the migrations repository |
| apply migrations other people wrote | Migrations for administrators | In the administration, Run, dry run and rollback |
| find your way around Setup > Migrations | A tour of Setup > Migrations | The status and the history |
| turn changes made by hand into a migration | Recording changes | Generating migrations, The migration editor |
| put the migrations on staging and production | Add a remote step by step | Deploy step by step |
| ship changes as a team, through CI to production | Team workflow with git | Testing migrations, Deploying with migrations |
| move from Doctrine Migrations, the Kaliop bundle or SQL update files | Coming from Doctrine Migrations | Kaliop, SQL update files |
The five commands of every day:
./console exp:migration:generate --skeleton add_news_table --apply # a new PHP migration in migrations/
./console exp:migration:check # the lint: names, headers, order, PHP (no database)
./console exp:migration:migrate # dry run: what would change
./console exp:migration:migrate --apply # caption, run, re-caption, commit, tag, push
./console exp:migration:status # what is done and what is pendingRun them from the installation root 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.
Who it is for
| You are ... | Your page |
|---|---|
| a software engineer who designs how changes reach production | Migrations for software engineers |
| a PHP developer who writes the migration classes | Writing migrations in PHP |
| an administrator who runs them on staging and production | Migrations for administrators |
| a hosting company or a database administrator | Migrations on hosted sites |
| an agency or integrator with many client sites | Migrations in client projects |
| a trainer | Lesson 9.5: Migrations, with an exercise |
| a DXP developer who knows Doctrine Migrations | Exponential migrations for Doctrine users |
Recipes
Each recipe is one task: what you will have at the end, the steps with their output, the complete migration, how to check it, how to take it back, and the next step. All recipes.
The database schema
- Add a database table
- Add a column or an index
- Engine notes: MySQL, PostgreSQL, SQLite, Oracle and MongoDB
Content classes and content
- Create or change a content class
- Add a class attribute
- Change content in bulk
- Fix data
- Seed content for a new site
- Large data migrations
Settings, roles and policies
Where migrations live and run
Quality
Teams and delivery
Safety and the record
Coming from another tool
In the administration
Setup > Migrations shows every migration with its state, runs the pending ones in the background, simulates a run and takes a run or a migration back, records changes, writes migrations in its editor, and deploys them to other installations. The dashboard has a Migrations block, and the website sidebar a panel. Every page below has step-by-step instructions with screenshots.
- A tour of Setup > Migrations: every tab with a screenshot, and which page for which task
- Migrations in the administration: the pages and who may use them
- The status and the history
- Run, dry run and rollback
- Migrations in the website sidebar
- Recording changes: record your own changes, or every change in a site-wide window, as the steps of a migration
- Remotes and deploys: the other installations this one deploys its migrations to, deploys all at once or stage by stage with a gate, live per remote, history and rollback
- Add a remote step by step: the five steps of the wizard, Test connection, edit and remove, FTP hosts with the trigger, self-healing
- Deploy step by step: choose remotes, preflight, deploy, follow it live, approve a gate, roll back, the history and the notice mails
- The migration editor: build a YAML migration with forms, check, preview and save it
- Generating migrations: from a recording, in the editor, from what is there, from a difference, skeletons
Reference
| Page | What it lists |
|---|---|
| The guide | the whole model: life cycle, files, order, header, environments, record, transactions, lock, every switch |
| PHP migrations | the class, its methods, the context, transactions, failure, events, testing |
| The migration file format | file names, the header, the order, the checksum, the record tables, the status file, the run log, the machine output |
| Commands | every exp:migration:* command, with a link to its generated page |
| Settings | every block of migration.ini, with a link to its generated page |
| Policies, views and events | the policies, the views of the module migration, the events and the audit events |
| The feature | what 6.0.15 adds, the classes, the engines, the limits |
| Upgrading with the console | exp:upgrade, whose steps are listed and run among the migrations |
When something goes wrong
- When a migration fails: troubleshooting by symptom
- Troubleshooting messages: every message the commands print
- Frequently asked questions
- Rollback and captions
YAML migrations
A migration can be a list of YAML steps instead of a PHP class: content, locations and versions, classes and class groups, users, user groups and roles, sections, languages and object states. The engine, its placeholders, conditions and loops: the file format; the step types: YAML migration steps and every step type. The recipes here are written in PHP; each of them can be written as YAML steps too where a step type covers it.
What 6.0.15 has, and what comes later
| In 6.0.15 | Not yet |
|---|---|
| PHP, YAML, SQL and INI migrations in the site, in active extensions and in installed packages | |
| the dry run, and the simulation with a diff on PostgreSQL and SQLite | a simulation on MySQL/MariaDB, Oracle and MongoDB (the plan is listed) |
| captions, the automatic restore, rollback of a run, of a migration and of any caption | |
| generators from a recording, from content, classes, roles, sections and settings, from a difference, and skeletons; the editor in the administration | |
commit, tag and push of every run's record; the cronjob part migrationpush | exp:velocity deploy --migrate |
| Setup > Migrations, background runs, recording, the editor, remotes and deploys, the dashboard block and the sidebar panel | |
the kernel's upgrade steps listed and run among the migrations (stages database and scripts) | the stages code, libraries and finish stay with exp:upgrade |
Related pages
- Migrations: the guide, the tutorial, PHP migrations
- All recipes, Frequently asked questions
- Migrations versus migrating a site
- Migrating to and from Exponential (moving a site from another system or release)
- Upgrading with the console, Upgrade steps for extensions
- Schema changes and migrations
- A tour of the administration
- Glossary
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.