Ibexa DXP v3.3 New Feature Preview: Migrations Bundle

A digital service often starts its life as a project, but it really comes alive after launch in continued maintenance. After the initial launch work continues as features are added and designs modified. During the pre-launch phase, adding and changing things are relatively easy because the system is not live yet. Once live, making changes requires more discipline, but this does not need to reduce development pace. With Ibexa DXP 3.3 we're adding a tool to make managing changes easier: Ibexa Migrations Bundle

Ibexa DXP has great tools for managing changes done in content and data, from built-in versioning to trash and more. Developers have long been accustomed to storing their code in version control, that tracks changes made. The practice been extended to hosting through the concept of Infrastructure as Code (IaC); service configuration is stored alongside application logic in version control. Needed infrastructure is deployed automatically based on this blueprint. This is how Ibexa Cloud works.

Tracking changes to the data structure is something that can also be done using version control. Database schema migrations mean storing changes to the database definitions as files that can be executed in other environments to replicate changes. Ibexa DXP uses relational databases to store raw data, but using database migrations to move changes to the content repository is not something that is feasible to do.

This is where Ibexa Migrations come in. This package allows defining changes to the repository in configuration files. These can be executed in any location and will make the changes to a particular environment. This allows a developer to add a new field on their local machine and generate a file defined that can be carried over to staging and finally into production. This reduces manual work and possibilities for human errors.

An overview of migrations in development

Migrations are a developer-facing feature that administrators and visitors will never be directly in contact with. To make it more understandable, let's consider a simple feature addition. There is a request to add an intro text field to blog posts and display it on top of the body text. Without using migrations the developer would need to either add the field manually to each database (production, staging and development) or add it to the production database and copy it to the other environments. The developer will also need to keep the code manually in sync with the database in use.

Manual copying the field definitions will always work, but it is laborsome and prone to typos and other mistakes. Making changes in the main database and copying it downstream works, but has some downsides: All data will be reset from the target database, and this might not be acceptable. Additionally it is wasteful to transfer the whole data mass around and is not feasible for large databases. And sometimes changes cannot be rolled into production (when creating a custom field type, for example). Ultimately neither of these are ideal.

With migrations we can export the changes to a lightweight migration file that is portable. Executing this migration will apply the changes to the repository there and then, similar to if you would do it manually via the administration interface. This file is also stored with the code version, in our example the template change that would display the intro text field. This ties both logic and data changes into a single deliverable. When this version is deployed the field is added and the code is updated.

A quick hands on with Ibexa Migrations

The migrations functionality runs completely as a command line application. Users have options to execute, generate and convert (more on that below) migration files. The files themselves are in human readable YAML, and can be created manually with a text editor. The markup to add the intro text field to the post is shown below:

-
    type: content_type
    mode: update
    match:
        field: content_type_identifier
        value: blog_post
    metadata:
        identifier: blog_post
    fields:
        -
            identifier: intro_text
            type: ezrichtext
            position: 5
            translations:
                eng-GB:
                    name: Intro text
            required: true
            searchable: true
            infoCollector: false
            translatable: true

Placed in the src/Migrations/Ibexa/ directory, it can be executed with the console:

$ ./bin/console ibexa:migrations:migrate
Please specify migration file:
add_intro_to_blog_post.yaml
done!

Adding it to version control makes it portable and easy to apply in any environment.

Migrations are an infrastructure feature

The initial release of the Migrations Bundle with Ibexa DXP will have the ability to work with locations, content and content types, metadata such as object states and sections as well as users and user groups. This does not cover all the possible use cases, but the most common ones. Going forward we will continue to add more capabilities, including for new features such as segments and the Segmentation API which was introduced in Ibexa DXP 3.2.

It is worth noting that there have been some third-party migration packages for predecessors of Ibexa DXP. Now with version 3.3 we add a similar option to our product. With a first-party option we can take full responsibility for maintaining and supporting it. With a clean-sheet implementation we have a contemporary base that will allow us to swiftly support new features that we adding to our repository.

Customers looking to upgrade to Ibexa DXP 3.3 and are already using a third-party option like the Kaliop Migrations Bundle can convert migration files to be Ibexa Migrations format. Third-party options will continue to work as long as they are compatible with the core software, but they will not be covered by product support. The recommended solution for Ibexa DXP 3.3 LTS version products (Ibexa Content, Ibexa Experience and Ibexa Commerce) is the included migration functionality.

Migrations are ultimately a utility to speed up development without sacrificing quality. You can adopt them gradually. The ibexa.co website, for example, has been developed without any migration solution in place, but will be using Ibexa Migrations in the coming months. Stay tuned for more hands-on blog posts on how Ibexa DXP can help you manage the complexity of Digital Experience Platform implementations.

Photo by Richard Lee on Unsplash