Migration recipes
Each recipe is one task, written the same way: what you'll have at the end, the steps with the commands and
their output, the complete migration, how to check it, how to roll it back, and the next step. They
assume Exponential 6.0.15 with the record tables (./console exp:upgrade:status shows 6.0.15-migration-tables as
done) and a development installation in a git checkout. New to migrations? Do the tutorial
first; it takes about 20 minutes.
The database schema
| Recipe | You will have |
|---|---|
| Add a database table | a table of your own on every engine, created from a .dba-style definition |
| Add a column or an index | a new column and index on an existing table, written by each engine's schema handler |
| Engine notes | what differs between MySQL/MariaDB, PostgreSQL, SQLite, Oracle and MongoDB |
Content classes and content
| Recipe | You will have |
|---|---|
| Create or change a content class | a content class with its attributes and class group, created or extended on every installation |
| Add a class attribute | a new attribute on an existing class, with the objects that exist initialized |
| Change content in bulk | many objects updated and published in one migration, found by class and subtree |
| Fix data | a correction of wrong data, written so it is safe on every installation |
| Seed content for a new site | the folders and pages a new site starts with, found again by remote id |
| Large data migrations | a long migration in batches that can be resumed after an interruption |
Settings, roles and policies
| Recipe | You will have |
|---|---|
| Move or rename INI settings | a setting moved in settings/override, with its old value kept and a way back |
| Add roles and policies | a role with its policies, assigned to a user group by remote id |
Where migrations live and run
| Recipe | You will have |
|---|---|
| Per-environment migrations | migrations limited to development, staging or production with the header line environments: |
| Migrations in an extension or a package | migrations shipped in an extension or an installed package, ordered with the site's |
| Upgrade step or migration? | the right tool for each change, and a migration that requires a kernel upgrade step |
Quality
| Recipe | You will have |
|---|---|
| Writing a reversible down() | a down() that really undoes up(), and proof that it does |
| Testing migrations | the lint in CI, a simulation with a diff, and a PHPUnit test on SQLite |
| Reviewing a migration | a checklist for the code review of a migration |
Teams and delivery
| Recipe | You will have |
|---|---|
| Team workflow with git | branches, ordering, requires: and merge conflicts handled |
| Deploying with migrations | a pipeline (with a GitHub Actions example) that checks and applies migrations |
| Pushing tags | every run committed, tagged and pushed, and failed pushes caught up |
Safety and the record
| Recipe | You will have |
|---|---|
| Captions and rollback in practice | a failed run restored, a run and a migration taken back |
| The audit trail of runs | the answer to "what ran where, when and by whom" |
Coming from another tool
| Recipe | You will have |
|---|---|
| Coming from Doctrine Migrations | the Doctrine commands and classes mapped to Exponential's |
| Coming from the Kaliop migration bundle | Kaliop YAML steps written as PHP migrations |
| Coming from SQL update files | a hand-written update file turned into a recorded, engine-aware migration |
YAML migrations
Coming with the YAML engine. Recipes for migrations written as YAML steps will be listed here when the YAML engine lands. In 6.0.15 every recipe is written in PHP.
Related pages
- Migrations: the hub
- 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
- Frequently asked questions
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.