Upgrade to Doctrine Migrations 3

Upgrading doctrine/migrations to version 3 (3.0.1) on a Symfony 4.4 project.

Even when following semver a major version upgrade is expected to have backwards compatibility breaks.

Fortunately in these cases, the migration steps have been relatively easy.

Upgrading the version

First off, as my setup is through Flex, to upgrade the Doctrine Migrations to v3, I needed to do this through symfony/orm-pack.

To upgrade, I run: composer update symfony/orm-pack --with-dependencies. This ended up updating 23 packages, including doctrine/migrations.

The issue

When composer finished updating, I saw the following error:

Script cache:clear returned with error code 1
!!  In ArrayNode.php line 327:
!!    Unrecognized options "dir_name, namespace" under "doctrine_migrations". Ava  
!!    ilable options are "all_or_nothing", "check_database_platform", "connection  
!!    ", "custom_template", "em", "factories", "migrations", "migrations_paths",   
!!    "organize_migrations", "services", "storage".                                
Script @auto-scripts was called via post-update-cmd

This meant that my current setup of config/packages/doctrine_migrations.yaml was no longer valid:

    dir_name: '%kernel.project_dir%/Migrations'
    namespace: DoctrineMigrations


Understanding the setup

The first place I looked at was the TreeBuilder which for this package was under vendor/doctrine/doctrine-migrations-bundle/DependencyInjection/Configuration.php (with PhpStorm can just click on doctrine_migrations in the yaml file and taken there, as long as you have the Symfony plugin installed).

There, looking at the arrayNode sections, I could see the different options available.

Having that as a reference, the Doctrine Migrations Documentation was now easier to navigate.

Making it work

Matching my previous setup took a few more than 3 lines, but I think it is easy to follow:

    all_or_nothing: true
    check_database_platform: true

        'DoctrineMigrations': '%kernel.project_dir%/Migrations'

            table_name: migration_versions
            version_column_name: version
            executed_at_column_name: executed_at



I run bin/console doctrine:migrations:diff first to see if everything still worked. But unfortunately I got the following error:

 The metadata storage is not up to date, please run the sync-metadata-storage command to fix this issue.

Running bin/console doctrine:migrations:migrate worked and then all the other commands after this run fine too.