Ibexa DXP Discussions

Community discussion forum for developers working with Ibexa DXP

eZ Platform content / database migration tips with Kaliop Migrations Bundle

Migrating content types and other database between environments is a common task. For example, if you develop a feature that requires changed to a content type in development environment and want to transfer it to staging and then on to production. You can do this manually by clicking using the interface, but it’s not feasible for larger project. And a chore at best.

eZ Platform itself (as of November 2017) does not come with a built in solution for content migrations. Instead you can use a third party Content Migration Bundle from Kaliop. This bundle allows exporting content types (and users, roles, policies, media…) into files that you can store in your version repository and workflow. Learn more on the introduction to eZ Migrations Bundle article.

For example, with Gitflow you could store the migration in your feature branch. The most common format used for content migrations is YAML, which is specified in documentation. In addition to YAML format, you can use free format PHP and SQL migrations as well.

This thread is open for tips on how to use migrations with eZ Platform.


In addition to importing, the bundle can also export database structures. For example, with this command you can export the content type with the identifier “landing_page” to a YAML file in your AppBundle:

./app/console kaliop:migration:generate \
    --type=content_type \
    --match-type=contenttype_identifier \
    --match-value=landing_page \

You can get all the options for the generate command with --help

1 Like

In many cases your databases in environments (dev/staging/prod) have different ID’s for content objects and locations. This can make running migrations non-trivial. There is a tip in the bundle’s FAQ section, to use Symfony parameters for the task:

A: use the ‘reference/set’ migration step to define a reference for the desired content Id, and use a Symfony parameter to store a different value for each Symfony environment. For example:

    type: reference
    mode: set
    identifier: content_id_ref
    value: '%a.parameter.name%'

    type: content
    mode: update
        content_id: "reference:content_id_ref"
    etc: ...

By default the command kaliop:migrations:migrate will require user input. This is not useful in CI environments, so for these cases you’ll want to run in non-interactive mode with -n, for example:

php app/console kaliop:migration:update -n

Nice tips @janit, thanks!

During development it is easy to get failing migrations and get in “failed” status. You can remove them manually from the database, but you can also use the migration command, as described in the Bundle docs:

php app/console kaliop:migration:migration migration_name --delete

After this you can execute migrations again.

eZ Platform EE landing pages and forms can also be migrated using the Kaliop Migrations bundle. For an example, see this thread: Migrating eZ Platform EE forms from development to production

So far I like using Kaliop Migrations. I can keep all my feature development including the schema changes in one branch. If my teammates need my changes, I send them the migration file and they get the new schema without having to lose any of their in progress work. So it helps avoiding having to manage multiple sql dump files that contain different schemas. This is handy when working on a shared branch.

I don’t like having to type out the long migration file name to delete the migration if it fails. That gets super old fast. I usually just do a backup, run the migration, if it doesn’t work I just restore the database and clear cache. Also remember to clear redis cache if you are using it.