UPGRADE.md

Upgrade to 3.6

Console

• The --all-or-nothing option for migrations:migrate does not accept a value anymore, and passing it a value will generate a deprecation. Specifying --all-or-nothing will wrap all the migrations to be executed into a single transaction, regardless of the specified configuration.

Upgrade to 3.1

• The "version" is the FQCN of the migration class (existing entries in the migrations table will be automatically updated).
• MigrationsEventArgs and MigrationsVersionEventArgs expose different API, please refer to the Code BC breaks section.

Console

• Console output changed. The commands use a different output style. If you were relying on specific output, please update your scripts. Console output is not covered by the BC promise, so please try not to rely on specific a output. Different levels of verbosity are available now (-v, -vv and -vvv ).
• The --show-versions option from migrations:status command has been removed, use migrations:list instead.
• The --write-sql option for migrations:migrate and migrations:execute does not imply dry-run anymore,
  use the --dry-run parameter instead.
• The --db option has been renamed to --conn.

Migrations table

• The migrations table now has a new column named execution_time.
• Running the migrations:migrate or migrations:execute command will automatically upgrade the migration table structure; a dedicated migrations:sync-metadata-storage command is available to sync manually the migrations table.

Migration template

• The <version> placeholder has been replaced by the <className> placeholder.

Configuration files

migrations.php Before

<?php

return [
    'name' => 'My Project Migrations',
    'migrations_namespace' => 'MyProject\Migrations',
    'table_name' => 'doctrine_migration_versions',
    'column_name' => 'version',
    'column_length' => 14,
    'executed_at_column_name' => 'executed_at',
    'migrations_directory' => '/data/doctrine/migrations-docs-example/lib/MyProject/Migrations',
    'all_or_nothing' => true,
    'check_database_platform' => true,
];

migrations.php After

<?php

return [

    'table_storage' => [
        'table_name' => 'doctrine_migration_versions',
        'version_column_name' => 'version',
        'version_column_length' => 191,
        'executed_at_column_name' => 'executed_at',
        'execution_time_column_name' => 'execution_time',
    ],

    'migrations_paths' => [
        'MyProject\Migrations' => '/data/doctrine/migrations/lib/MyProject/Migrations',
        'MyProject\Component\Migrations' => './Component/MyProject/Migrations',
    ],

    'all_or_nothing' => true,
    'check_database_platform' => true,
];

Files in XML, YAML or JSON also changed in a similar way. Please refer to the official documentation for more details.

Note: the name property has been removed.

Note: the option in table_storage needs to be updated only if you have changed the metadata table settings by using v2 options such as table_name, column_name, column_length or executed_at_column_name. If you did not change those settings, it is recommended to not provide the options and let doctrine figure out the best settings.

Code BC breaks

Most of the code is protected by the @internal declaration and in a very rare cases you might have dealt with the internals of this library.

The most important BC breaks are in the Doctrine\Migrations\Configuration\Configuration class and in the helper system that now has been replaced by the Doctrine\Migrations\DependencyFactory functionalities.

Here is a list of the most important changes:

• Namespace Doctrine\Migrations\Configuration\Configuration
  • CHANGED: Class Doctrine\Migrations\Configuration\Configuration became final
  • REMOVED: Constant Doctrine\Migrations\Configuration\Configuration::VERSION_FORMAT was removed, there is not more limitation on the version format
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#__construct() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setName() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getName() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getConnection() was removed, use Doctrine\Migrations\DependencyFactory#getConnection()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsTableName() was removed, use Doctrine\Migrations\Configuration\Configuration#setMetadataStorageConfiguration with an instance of Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsTableName() was removed, use Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration#getMetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsColumnName() was removed, use Doctrine\Migrations\Configuration\Configuration#setMetadataStorageConfiguration with an instance of Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsColumnName() was removed, use Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration#getMetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getQuotedMigrationsColumnName() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsColumnLength() was removed, use Doctrine\Migrations\Configuration\Configuration#setMetadataStorageConfiguration with an instance of Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsColumnLength() was removed, use Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration#getMetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsExecutedAtColumnName() was removed, use Doctrine\Migrations\Configuration\Configuration#setMetadataStorageConfiguration with an instance of Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsExecutedAtColumnName() was removed, use Doctrine\Migrations\Metadata\Storage\MetadataStorageConfiguration#getMetadataStorageConfiguration
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getQuotedMigrationsExecutedAtColumnName() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsDirectory() was removed, use Doctrine\Migrations\Configuration\Configuration#addMigrationsDirectory()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsDirectory() was removed, use Doctrine\Migrations\Configuration\Configuration#getMigrationDirectories()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsNamespace() was removed, use Doctrine\Migrations\Configuration\Configuration#addMigrationsDirectory()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsNamespace() was removed, use Doctrine\Migrations\Configuration\Configuration#getMigrationDirectories()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setMigrationsFinder() was removed, use the dependency factory instead
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsFinder() was removed, use the dependency factory instead
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#hasVersionMigrated() was removed, use the dependency factory instead
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getVersionData() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#resolveVersionAlias() was removed, use Doctrine\Migrations\Version\AliasResolver#resolveVersionAlias()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#isMigrationTableCreated() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#createMigrationTable() was removed, use Doctrine\Migrations\Metadata\Storage\MetadataStorage#ensureInitialized()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getDateTime() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#generateVersionNumber() was removed, use Doctrine\Migrations\Generator\ClassNameGenerator#generateClassName()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#connect() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#dispatchMigrationEvent() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#dispatchVersionEvent() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#dispatchEvent() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getNumberOfExecutedMigrations() was removed, use Doctrine\Migrations\DependencyFactory#getMetadataStorage()->getExecutedMigrations()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getNumberOfAvailableMigrations() was removed, use Doctrine\Migrations\DependencyFactory#getMigrationRepository()->getMigrations()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getLatestVersion() was removed, use Doctrine\Migrations\Version\AliasResolver#resolveVersionAlias()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigratedVersions() was removed, use Doctrine\Migrations\DependencyFactory#getMetadataStorage()->getExecutedMigrations()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getAvailableVersions() was removed use Doctrine\Migrations\DependencyFactory#getMigrationRepository()->getMigrations()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getCurrentVersion() was removed, use Doctrine\Migrations\Version\AliasResolver#resolveVersionAlias()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#registerMigrationsFromDirectory() was removed, use Doctrine\Migrations\Configuration\Configuration#addMigrationsDirectory()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#registerMigration() was removed, use Doctrine\Migrations\Configuration\Configuration#addMigrationClass()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#registerMigrations() was removed use Doctrine\Migrations\Configuration\Configuration#addMigrationClass()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrations() was removed, use Doctrine\Migrations\DependencyFactory#getMigrationRepository()->getMigrations()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getVersion() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getMigrationsToExecute() was removed, use Doctrine\Migrations\Version\MigrationPlanCalculator#getPlanUntilVersion() to create a migration plan
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getPrevVersion() was removed, use Doctrine\Migrations\Version\AliasResolver#resolveVersionAlias()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getNextVersion() was removed, use Doctrine\Migrations\Version\AliasResolver#resolveVersionAlias()
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getRelativeVersion() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getDeltaVersion() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#setOutputWriter() was removed, set the Psr\Log\LoggerInterface service in Doctrine\Migrations\DependencyFactory
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getOutputWriter() was removed, get the Psr\Log\LoggerInterface service from Doctrine\Migrations\DependencyFactory
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getQueryWriter() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#getDependencyFactory() was removed
  • REMOVED: Method Doctrine\Migrations\Configuration\Configuration#validate() was removed
  • Namespace Doctrine\Migrations\Configuration\Connection\Loader\Exception
    • REMOVED: Class Doctrine\Migrations\Configuration\Connection\Loader\Exception\LoaderException has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Connection\Loader\Exception\InvalidConfiguration has been deleted
  • Namespace Doctrine\Migrations\Configuration\Exception
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\ParameterIncompatibleWithFinder has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\InvalidConfigurationKey has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\MigrationsNamespaceRequired has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\XmlNotValid has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\YamlNotAvailable has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\FileAlreadyLoaded has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\JsonNotValid has been deleted
    • REMOVED: Class Doctrine\Migrations\Configuration\Exception\YamlNotValid has been deleted
    • CHANGED: The number of required arguments for Doctrine\Migrations\Configuration\Exception\FileNotFound::new() increased from 0 to 1
• Namespace Doctrine\Migrations\Event\MigrationsEventArgs
  • CHANGED: Class Doctrine\Migrations\Event\MigrationsEventArgs became final
  • REMOVED: Method Doctrine\Migrations\Event\MigrationsEventArgs#getConfiguration() was removed
  • REMOVED: Method Doctrine\Migrations\Event\MigrationsEventArgs#getDirection() was removed, use Doctrine\Migrations\Event\MigrationsEventArgs#getPlan()
  • REMOVED: Method Doctrine\Migrations\Event\MigrationsEventArgs#isDryRun() was removed, use Doctrine\Migrations\Event\MigrationsEventArgs#getMigratorConfiguration()
  • CHANGED: Doctrine\Migrations\Event\MigrationsEventArgs#__construct() arguments have been updated
  • Namespace Doctrine\Migrations\Event\MigrationsVersionEventArgs
    • CHANGED: Class Doctrine\Migrations\Event\MigrationsVersionEventArgs became final
    • REMOVED: Method Doctrine\Migrations\Event\MigrationsVersionEventArgs#getVersion() was removed use Doctrine\Migrations\Event\MigrationsEventArgs#getPlan()
• Namespace Doctrine\Migrations\Finder
  • REMOVED: These ancestors of Doctrine\Migrations\Finder\RecursiveRegexFinder have been removed: ["Doctrine\Migrations\Finder\MigrationDeepFinder"]
  • REMOVED: Class Doctrine\Migrations\Finder\MigrationDeepFinder has been deleted
• Namespace Doctrine\Migrations\Tools\Console\Command
  • CHANGED: All non abstract classes in Doctrine\Migrations\Tools\Console\Command\* became final
  • REMOVED: Class Doctrine\Migrations\Tools\Console\Command\AbstractCommand has been renamed into Doctrine\Migrations\Tools\Console\Command\DoctrineCommand and has been marked as internal
  • CHANGED: Method Doctrine\Migrations\Tools\Console\Command\*Command#__construct() changed signature into (?Doctrine\Migrations\DependencyFactory $di, ?string $name)
  • CHANGED: Method initialize() of Class Doctrine\Migrations\Tools\Console\Command\AbstractCommand visibility reduced from public to protected
  • CHANGED: Method execute() of Class Doctrine\Migrations\Tools\Console\Command\*Command visibility reduced from public to protected
  • REMOVED: Method Doctrine\Migrations\Tools\Console\Command\DiffCommand#createMigrationDiffGenerator() was removed
  • Namespace Doctrine\Migrations\Tools\Console\Exception
    • CHANGED: The number of required arguments for Doctrine\Migrations\Tools\Console\Exception\SchemaDumpRequiresNoMigrations::new() increased from 0 to 1
    • REMOVED: Class Doctrine\Migrations\Tools\Console\Exception\ConnectionNotSpecified has been deleted
  • Namespace Migrations\Tools\Console\Helper
    • REMOVED: All classes and namespaces are marked as internal or have been removed, use Doctrine\Migrations\DependencyFactory instead
• Namespace Doctrine\Migrations\AbstractMigration
  • CHANGED: The method Doctrine\Migrations\AbstractMigration#__construct() changed signature into (Doctrine\DBAL\Connection $conn, PSR\Log\LoggerInterface $logger)
  • CHANGED: The method Doctrine\Migrations\AbstractMigration#down() is not abstract anymore, the default implementation will abort the migration process
  • REMOVED: Property Doctrine\Migrations\AbstractMigration#$version was removed
• Namespace Doctrine\Migrations\Provider
  • REMOVED: Class Doctrine\Migrations\Provider\SchemaProviderInterface has been deleted
  • REMOVED: These ancestors of Doctrine\Migrations\Provider\StubSchemaProvider have been removed: ["Doctrine\Migrations\Provider\SchemaProviderInterface"]
• Namespace Doctrine\Migrations\Exception
  • REMOVED: Class Doctrine\Migrations\Exception\MigrationNotConvertibleToSql has been deleted
  • REMOVED: Class Doctrine\Migrations\Exception\MigrationsDirectoryRequired has been deleted
• REMOVED: Class Doctrine\Migrations\Version\Factory became the interface Doctrine\Migrations\Version\MigrationFactory
• REMOVED: Class Doctrine\Migrations\OutputWriter has been deleted, use Psr\Log\Loggerinterface

Upgrade to 2.0

BC Break: Moved Doctrine\DBAL\Migrations to Doctrine\Migrations

Your migration classes that previously used to extend Doctrine\DBAL\Migrations\AbstractMigration now need to extend Doctrine\Migrations\AbstractMigration instead. The Doctrine\DBAL\Migrations\AbstractMigration class will be deprecated in the 1.8.0 release to prepare for the BC break.

BC Break: Removed Doctrine\DBAL\Migrations\MigrationsVersion

The Doctrine\DBAL\Migrations\MigrationsVersion class is no longer available: please refrain from checking the Migrations version at runtime.

BC Break: Moved Doctrine\Migrations\Migration to Doctrine\Migrations\Migrator

To make the name more clear and to differentiate from the AbstractMigration class, Migration was renamed to Migrator.

BC Break: Moved exception classes from Doctrine\Migrations\%name%Exception to Doctrine\Migrations\Exception\%name%

doctrine#636 Follows concept introduced in ORM (doctrine/orm#6743 + doctrine/orm#7210) and naming follows pattern accepted in Doctrine CS.

Upgrade from 1.0-alpha1 to 1.0.0-alpha3

AbstractMigration

Before:

The method getName() was defined and it's implementation would change the order in which the migration would be processed. It would cause discrepancies between the file order in a file browser and the order of execution of the migrations.

After:

The getName() method as been removed | set final and new getDescription() method has been added. The goal of this method is to be able to provide context for the migration. This context is shown for the last migrated migration when the status command is called.

--write-sql option from the migrate command

Before:

The --write-sql option would only output sql contained in the migration and would not update the table containing the migrated migrations.

After:

That option now also output the sql queries necessary to update the table containing the state of the migrations. If you want to go back to the previous behavior just make a request on the bug tracker as for now the need for it is not very clear.

MigrationsVersion::VERSION

Before:

MigrationsVersion::VERSION used to be a property. The returned value was fanciful.

After:

It is now a a function so that a different value can be automatically send back if it's a modified version that's used. The returned value is now the git tag. The tag is in lowercase as the other doctrine projects.