Migrations versus migrating a site
The documentation uses the word migration for two different jobs. This page tells them apart and sends you to the right pages.
| Migrations (schema and content changes) | Migrating a site (moving or upgrading an installation) | |
|---|---|---|
| What changes | one site's database, content classes, content, roles or settings, a little at a time | where a whole installation runs, which release it runs, or which system its content comes from |
| How often | many times, with every change the site's team makes | once per move, per upgrade or per import |
| Written as | a PHP file YYYYMMDDHHMMSS_name.php in migrations/, under version control | a plan, a checklist, and tools such as dumps, exports and the upgrade |
| Run with | ./console exp:migration:migrate --apply, or Setup > Migrations | ./console exp:upgrade, database dumps, package export and import, import tools |
| Recorded in | the tables exp_migration and exp_migration_run, and a status file in git | the project's own notes; exp:upgrade records its steps |
| Applied to | every installation of the site: development, staging, production | the one installation being moved, upgraded or filled |
| Start here | Migrations | Migrating to and from Exponential |
Which one do you need?
| You want to ... | It is | Read |
|---|---|---|
| add a table, a column or an index for your site | a migration | Add a database table |
| add a content class or an attribute, on every installation | a migration | Create or change a content class |
| change or fix content on every installation the same way | a migration | Change content in bulk, Fix data |
| give a role new policies on staging and production | a migration | Add roles and policies |
| bring an installation to a new Exponential release | migrating (an upgrade) | Upgrading, Upgrading with the console |
| move a site to another server or hosting company | migrating a site | Moving a site between hosts |
| move a site to another database engine | migrating a site | Moving a site to another engine, Changing a customer site's database engine |
| bring a site over from WordPress, Drupal or another system | migrating a site | Migrating to and from Exponential, From another system |
| bring a site over from eZ Platform or Ibexa | migrating a site | From eZ Platform or Ibexa |
| upgrade from an older Exponential release | migrating a site | From an older Exponential release |
| move layouts, settings and templates between sites | neither: the Layouts examples | Migrate examples |
Where the two meet
- After an upgrade, migrations take over.
exp:upgradebrings an installation to a new release with the kernel's upgrade steps. Those steps are also listed among the migrations (as migrations of the sourcekernel), and a migration run applies the pending ones of the stagesdatabaseandscriptsbefore the site's own migrations (The steps among the migrations). A site migration that needs a step's table names it inrequires:. - After a move or an import, migrations keep the copies alike. Once a migrated site runs on development, staging and production, every further change (a new class, a role, a fix) is a migration, so all three stay the same (Per-environment migrations).
- A move of the database engine is not a migration. Migrations change a site on the engine it runs on; moving
between engines is a dump and a load (Moving a site to another engine).
The migrations themselves keep working on the new engine when they use
$context->db()and the schema handlers (Engine notes). - Captions serve both. A migration run and
exp:upgradetake the same kind of caption (a safe point) and share the installation lock, so an upgrade and a migration run never write at the same time (Captions and rollback in practice).
The pages of each family
Migrations (this section of the help): Migrations · the guide · the tutorial · the recipes · In the administration · FAQ
Migrating a site:
- Migrating to and from Exponential: the hub, with a guide per source system
- Migrating to Exponential: for organizations adopting Exponential
- Migrating customers: overview: for hosting companies
- Migrating to Exponential: course overview: the trainers' course
- Upgrading and Upgrading with the console
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, Settings, Policies, views and events
- The file format, The feature
- When a migration fails, Troubleshooting messages
- Upgrade step or migration?
- Glossary
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.