Database Migration
Modules can have their own migrations. To get comprehensive information about migrations in OXID eShop, check the database migrations documentation under Migrations.
Configuration
Put the migration configuration file into the migration folder inside the module’s root directory:
├── migration
└── migrations.yml
Example of migrations.yml:
table_storage:
table_name: oxmigrations_ddoewysiwyg
migrations_paths:
'OxidEsales\WysiwygModule\Migrations': data
Tip
To prevent database table name conflicts, include your module’s ID in table_name.
Migration Classes
Most recent info on requirements and structure of Migration Classes can be found in Doctrine Migrations documentation.
To generate a blank migration class for your module, call the Doctrine Migrations CLI directly with your module’s configuration (see also Calling Doctrine Migrations directly):
vendor/bin/doctrine-migrations migrations:generate \
--configuration=<path-to-module>/migration/migrations.yml
Warning
When planning your Migration’s structure, remember that certain SQL statements will issue Implicit commits which will affect the transaction functionality and may have unexpected side-effects.
Registration
Module migrations placed in the migration folder as described above are discovered
automatically: the shop scans the migration/migrations.yml of every installed module and
executes the migrations via oe:database:migrate.
Note
Auto-discovery only covers installed modules, and only at the fixed path
migration/migrations.yml. A component is never scanned, and a
module that keeps its migration configuration elsewhere is not discovered either — both must
register their migrations through the DI tag shown below.
Migrations can also be registered explicitly through the Symfony service container using the
oxid_esales.migration_path_provider DI tag (see Tagged migrations). This is the way to
expose migrations that auto-discovery does not cover — those of a component, or of a module whose
migration configuration lives outside the auto-discovered migration/migrations.yml path.
Place the configuration in a folder that is not the auto-discovered migration one (for
example di_migrations), implement MigrationPathProviderInterface and register the service:
<?php
use OxidEsales\EshopCommunity\Internal\Framework\Migration\MigrationPathProviderInterface;
class MyModuleMigrationPathProvider implements MigrationPathProviderInterface
{
public function getMigrationConfigPath(): string
{
return __DIR__ . '/../di_migrations/migrations.yaml';
}
}
Warning
Do not register the same migrations through both mechanisms. Migrations from an installed
module’s auto-discovered migration/migrations.yml are already registered automatically.
Adding a DI tag for the same path registers them twice.
Use the DI tag only for paths outside migration/ or for components, never for an
auto-discovered module path.
services:
MyVendor\MyModule\MyModuleMigrationPathProvider:
tags:
- { name: 'oxid_esales.migration_path_provider' }
Note
Where you register the provider decides when it is available:
In
services.yamlit is only picked up byoe:database:migrateonce the module has been activated viaoe:module:activate.In bootstrap-services.yaml it is available for every installed module, so the migrations can be run before the module is activated.
Usage
To apply all pending migrations including module migrations, run:
vendor/bin/oe-console oe:database:migrate
Note
oe:database:migrate is the supported entry point. The older doctrine-migration wrapper
(vendor/bin/oe-eshop-doctrine_migration, backed by the Migrations / MigrationsBuilder
classes) is deprecated in favour of it.
For more details on how the migration system works, see Migrations.