Migrations

OXID eShop uses database migrations for:

Infrastructure

OXID eShop uses Doctrine Migrations integrated via OXID eShop migration components.

Prior to v3.0, Doctrine Migrations was not able to collect migrations from multiple folders/namespaces and to specify dependencies between them. But there was a need to run migration for one or all the projects and modules (CE, PE, EE, PR and a specific module). For this reason, we have created the OXID eShop Doctrine Migration Wrapper.

The Doctrine Migration Wrapper needs some information about the OXID eShop installation like:

  • what edition is active

  • what are credentials for database

This information is gathered from OXID eShop Facts.

OXID eShop Facts has a class which can provide an information about OXID eShop and its environment. This component is shop-independent and can be used without bootstrap. The only restriction is to have the config.inc.php file configured.

Using migrations

Running migrations - CLI

The script to run migrations is installed within Composer’s bin directory. It accepts two parameters:

  • Doctrine Command

  • Suite Type (CE, PE, EE, PR or a specific module_id)

vendor/bin/oe-eshop-db_migrate <Doctrine_Command> <Suite_Type>

Important

For the comprehensive and up-to-date info, consult the Doctrine Migrations official documentation.

Example:

vendor/bin/oe-eshop-db_migrate migrations:migrate

This command will run all the migrations which are in OXID eShop specific directories. If you have the OXID eShop Enterprise edition, for example, the migration tool will run migrations in this order:

  • Community Edition migrations (executed always)

  • Professional Edition migrations (executed when eShop has PE or EE)

  • Enterprise Edition migrations (executed when eShop has EE)

  • Project specific migrations (executed always)

  • Module migrations (executed when eShop has at least one module with migration)

Suite Types (Generate migration for a single suite)

It is also possible to run migrations for a specific suite by defining <Suite_Type> parameter in the command. This variable defines what type of migration it is. There are 5 suite types:

  • PR - For project specific migrations. It should be always used for project development.

  • CE - Generates migration file for OXID eShop Community Edition. It’s used for product development only.

  • PE - Generates migration file for OXID eShop Professional Edition. It’s used for product development only.

  • EE - Generates migration file for OXID eShop Enterprise Edition. It’s used for product development only.

  • <module_id> - Generates migration file for OXID eShop specific module. It’s used for module development only.

Example 1:

vendor/bin/oe-eshop-db_migrate migrations:generate

This command generates migration versions for all the suite types.

Example 2:

vendor/bin/oe-eshop-db_migrate migrations:generate EE

In this case, it will be generated only for Enterprise Edition in vendor/oxid-esales/oxideshop_ee/migration directory.

Calling Doctrine Migrations directly:

OXID Migration Wrapper makes it easy to manage complete sets of project’s migrations with a single command. You can always bypass this component and just call Doctrine Migration’s executable directly to use migrations in any other scenario:

# calling OXID Migration Wrapper's executable vs.
vendor/bin/oe-eshop-db_migrate

# calling Doctrine Migration's executable
vendor/bin/doctrine-migrations

For example:

  • to execute a single migration file, run:

vendor/bin/doctrine-migrations execute \
    --up \
    'OxidEsales\EshopCommunity\Migrations\Version1234567890' \
    --db-configuration 'vendor/oxid-esales/oxideshop-doctrine-migration-wrapper/src/migrations-db.php' \
    --configuration source/migration/migrations.yml

Using Migrations Wrapper without CLI

Doctrine Migration Wrapper is written in PHP and also could be used without command line interface. To do so:

  • Create Migrations object with MigrationsBuilder->build()

  • Call execute method with needed parameters