Doctrine migrations #

This page is for developers who change the database of a DXP project, or deploy changes that do. The DXP requires doctrine/doctrine-migrations-bundle; the skeleton's guide runs migrations on every update and deploy.

Contents #

1. Install versus migrate
2. The commands
3. Your own tables
4. In a deploy
5. Rules

Install versus migrate #

Never run the install command against a database with content to "update" it.

The commands #

From the guide's CLI reference (section 22.2):

php bin/console doctrine:migration:status                         # pending and applied
php bin/console doctrine:migration:migrate --dry-run              # preview the SQL
php bin/console doctrine:migration:migrate --allow-no-migration   # apply pending migrations
php bin/console doctrine:migration:diff                           # generate a migration from your entity changes
php bin/console doctrine:migration:execute --up <version>         # one migration up
php bin/console doctrine:migration:execute --down <version>       # roll one back
php bin/console doctrine:schema:validate                          # mapping versus database

Your own tables #

If your project stores its own data with Doctrine entities in src/Entity/, change the entity, generate a migration with doctrine:migration:diff, read the generated SQL, and commit the migration with the code that needs it. Test it on every database engine you support: MySQL, PostgreSQL and SQLite differ in types and in what ALTER TABLE can do.

Store content in the content repository (content types and fields), not in your own tables, unless it truly is not content: then it gets the repository's versions, translations, permissions and APIs for free.

In a deploy #

php bin/console doctrine:migration:migrate --allow-no-migration --env=prod

Back up the database before, run migrations before the new code serves traffic, and clear the cache after (Deploying).

Rules #

• A migration that has run anywhere is never edited; write a new one.
• A migration must work on an empty database and on production data.
• doctrine:database:drop --force exists; never run it on a server you did not mean to wipe.

Related pages #

• Updating
• Deploying
• Databases
• Migrations in Exponential 6 (the hub), Coming from Doctrine Migrations
• Exponential migrations for Doctrine users
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.