You can use migrations in projects that require the same data to be present across multiple instances. They can be useful for project templates. Migrations are able to store shared data, so they can be applied for each new project you start, or incrementally upgrade older projects to your new standard, if needed. They are a developer-friendly tool that allows you to share data without writing code.
You can migrate your Repository data, that is Content items, as well as Content Types, languages, Object states, Sections, etc., between installations by using the migration command.
Public PHP API
You can also manage data migrations with the PHP API, see Managing migrations.
Do not enable EzMigrationBundle2
If you are migrating your data either with
ezsystems/ezmigrationbundle, do not install the
tanoconsulting/ezmigrationbundle2 package, or your application will stop working due to multiple duplicated classes.
As of v3.3.3, the
ezmigrationbundle package has been removed to mitigate this issue.
It is recommended that you use the default
ibexa/migrations package to migrate your data.
To see an example of migrations in action, export data already present in your installation.
To export Repository content, use the
This command generates a YAML file with the requested part of the Repository.
The file is located by default in the
or in a custom folder that you configure.
You can later use this file to import the data.
This generates a file containing all Content items. Below you can see part of the output of the default Ibexa DXP installation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
The output contains all the possible information for a future migration command. Parts of it can be removed or modified. You can treat it as a template for another Content item for user group. For example, you could:
referencesif you don't intend to store IDs for future use (see migration references)
locationRemoteId, as those are generated if not passed (just like in PHP API)
- Add fields for other languages present in the system.
Similarly, you can create update and delete operations.
They are particularly useful combined with
This option is automatically added as part of
match expression in the update/delete migration:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
Note that you should test your migrations. See migrating data.
Migration command can be executed with database rollback at the end with the
--type option defines the type of Repository data to export.
The following types are available:
If you do not provide the
--type option, the command asks you to select a type of data.
--mode option defines the action that importing the file performs.
The following modes are available:
create- creates new items
update- updates an existing item. Only covers specified fields and properties. If the item does not exist, causes an error.
delete- deletes an existing item. If the item does not exist, causes an error.
If you do not provide the
--mode option, the command asks you to select the mode.
The following combinations of types are modes are available:
--match-property option, together with
value, enables you to select which data from the Repository to export.
match-property defines what property should be used as a criterion for selecting data.
The following properties are available (per type):
--value option, together with
match-property, filters the Repository content that the command exports.
value defines which values of the
match-property should be included in the export.
For example, to export only Article Content items, use the
content_type_identifier match property with
article as the value:
value is added to generated
delete type migration files.
--file option defines the name of the YAML file to export to.
When migrating multiple files at once (for example when calling
ibexa:migration:migrate without options),
they are executed in alphabetical order.
--user-context option enables you to run the export command as a specified User.
The command only exports Repository data that the selected User has access to.
By default the admin account is used, unless specifically overridden by this option or in
bundle configuration (
To import Repository data from YAML files, run the
Place your import file in the
or in a custom folder that you configure.
The command takes the file name within this folder as parameter.
If file is not specified, all files within this directory are used.
Ibexa Migrations store execution metadata in
ibexa_migrations database table. This allows incremental upgrades:
ibexa:migration:migrate command ignores files that it had previously executed.
Converting migration files¶
If you want to convert a file from the format used by the
Kaliop migration bundle
to the current migration format, use the
The source file must use Kaliop mode and type combinations. The converter handles Kaliop types that are different from Ibexa types.
You can also convert multiple files using
If you do not specify the output folder, the command overwrites the input files.
Adding migration files¶
ibexa:migrations:import command to add files to the migration folder defined in configuration
Checking migration status¶
To check the status of migration files in the migration folder defined in configuration, run the following command:
The command lists the migration files and indicates which of them have already been migrated.
The default migration folder is
You can configure a different folder by using the following settings:
1 2 3
Some migration steps can contain a special
You can find which migration steps support actions in the table below:
Actions are optional operations that can be run after the main "body" of a migration has been executed (that is, content has been created / updated, Object state has been added, and so on). Their purpose is to allow additional operations to be performed as part of this particular migration. They are executed inside the same transaction, so in the event of failure they cause database rollback to occur.
For example, when updating a Content Type object, some fields might be removed:
1 2 3 4 5 6 7 8 9 10 11
When executed, this migration:
- Finds Content Type using its identifier (
- Assigns Content Type Group "Media"
- Removes it from Content Type Group "Content"
- Removes the
- Removes its existing drafts, if any.
Available migration actions¶
The following migration actions are available out of the box:
assign_parent_location(Content Create / Update)
assign_content_type_group(Content Type Create / Update)
remove_drafts(Content Type Update)
remove_field_by_identifier(Content Type Update)
unassign_content_type_group(Content Type Update)
assign_role_to_user(Role Create / Update)
assign_role_to_user_group(Role Create / Update)
assign_user_to_role(User Create / Update)
assign_user_group_to_role(User Group Create / Update)
In contrast with Kaliop migrations, actions provide you with ability to perform additional operations and extend the migration functionality. See creating your own Actions.
References are key-value pairs necessary when one migration depends on another.
Since some migrations generate object properties (like IDs) during their execution, which cannot be known in advance,
references provide migrations with the ability to use previously created object properties in further migrations.
They can be subsequently used by passing them in their desired place with
The example below creates a Content item of type "folder", and stores its Location path as
Then this reference is reused as part of a new role, as a limitation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
By default, reference files are located in a separate directory
(see configuration reference
Reference files are NOT loaded by default. A separate step (type: "reference", mode: "load", with filename as "value") is required. Similarly, saving a reference file is done using type: "reference", mode: "save" step, with filename.
1 2 3 4 5 6 7 8 9 10
You don't need to save references if they are used in the same migration file. References are stored in memory during migration, whether they are used or not.
Creating your own actions¶
To create an action, you need:
- An action class, to store any additional data that you might require.
- An action denormalizer, to convert YAML definition into your action class.
- An action executor, to handle the action.
The following example shows how to create an action that assigns a Content item to a Section.
First, create an action class, in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
Then you need a denormalizer to convert data that comes from YAML into an action object,
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Then, tag the action denormalizer so it is recognized by the serializer used for migrations.
1 2 3 4 5
And finally, add an executor to perform the action, in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
Tag the executor with
ibexa.migrations.executor.action.<type> tag, where
<type> is the "type" of the step
that executor works with (
location, and so on).
The tag has to have a
key property with the action type.
1 2 3
You can get default configuration along with option descriptions by executing the following command: