Migration Classes

Migration classes must extend Doctrine\Migrations\AbstractMigration and at a minimum they must implement the up and down methods. You can easily generate a blank migration to modify with the following command:

$ ./vendor/bin/doctrine-migrations generate
Generated new migration class to "/data/doctrine/migrations-docs-example/lib/MyProject/Migrations/Version20180601193057.php"

To run just this migration for testing purposes, you can use migrations:execute --up 'MyProject\Migrations\Version20180601193057'

To revert the migration you can use migrations:execute --down 'MyProject\Migrations\Version20180601193057'

The above command will generate a PHP class with the path to it visible like above. Here is what the blank migration looks like:

1 <?php

declare(strict_types=1);

namespace MyProject\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

/**
 * Auto-generated Migration: Please modify to your needs!
 */
final class Version20180601193057 extends AbstractMigration
{
    public function getDescription(): string
    {
        return '';
    }

    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs

    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs

    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Methods to Implement

The AbstractMigration class provides a few methods you can override to define additional behavior for the migration.

isTransactional

Override this method if you want to disable transactions in a migration. It defaults to true.

1 public function isTransactional(): bool
{
    return false;
}
2
3
4

Some database platforms like MySQL or Oracle do not support DDL statements in transactions and may or may not implicitly commit the transaction opened by this library as soon as they encounter such a statement, and before running it. Make sure to read the manual of your database platform to know what is actually happening. isTransactional() does not guarantee that statements are wrapped in a single transaction. To learn more about this, read the dedicated explanation.

getDescription

Override this method if you want to provide a description for your migration. The value returned here will get outputted when you run the ./vendor/bin/doctrine-migrations status --show-versions command.

1 public function getDescription(): string
{
    return 'The description of my awesome migration!';
}
2
3
4

preUp

This method gets called before the up() is called.

1 public function preUp(Schema $schema): void
{
}
2
3

postUp

This method gets called after the up() is called.

1 public function postUp(Schema $schema): void
{
}
2
3

preDown

This method gets called before the down() is called.

1 public function preDown(Schema $schema): void
{
}
2
3

postDown

This method gets called after the down() is called.

1 public function postDown(Schema $schema): void
{
}
2
3

Methods to Call

The AbstractMigration class provides a few methods you can call in your migrations to perform various functions.

warnIf

Warn with a message if some condition is met.

1 public function up(Schema $schema): void
{
    $this->warnIf(true, 'Something might be going wrong');

    // ...
}
2
3
4
5
6

abortIf

Abort the migration if some condition is met:

1 public function up(Schema $schema): void
{
    $this->abortIf(true, 'Something went wrong. Aborting.');

    // ...
}
2
3
4
5
6

skipIf

Skip the migration if some condition is met.

1 public function up(Schema $schema): void
{
    $this->skipIf(true, 'Skipping this migration.');

    // ...
}
2
3
4
5
6

addSql

You can use the addSql method within the up and down methods. Internally the addSql calls are passed to the executeQuery method in the DBAL. This means that you can use the power of prepared statements easily and that you don't need to copy paste the same query with different parameters. You can just pass those different parameters to the addSql method as parameters.

1 public function up(Schema $schema): void
{
    $users = [
        ['name' => 'mike', 'id' => 1],
        ['name' => 'jwage', 'id' => 2],
        ['name' => 'ocramius', 'id' => 3],
    ];

    foreach ($users as $user) {
        $this->addSql('UPDATE user SET happy = true WHERE name = :name AND id = :id', $user);
    }
}
2
3
4
5
6
7
8
9
10
11
12

write

Write some debug information to the console.

1 public function up(Schema $schema): void
{
    $this->write('Doing some cool migration!');

    // ...
}
2
3
4
5
6

throwIrreversibleMigrationException

If a migration cannot be reversed, you can use this exception in the down method to indicate such. The throwIrreversibleMigrationException method accepts an optional message to output.

1 public function down(Schema $schema): void
{
    $this->throwIrreversibleMigrationException();

    // ...
}
2
3
4
5
6

Next Chapter: Managing Migrations

1	<?php declare(strict_types=1); namespace MyProject\Migrations; use Doctrine\DBAL\Schema\Schema; use Doctrine\Migrations\AbstractMigration; /** * Auto-generated Migration: Please modify to your needs! */ final class Version20180601193057 extends AbstractMigration { public function getDescription(): string { return ''; } public function up(Schema $schema): void { // this up() migration is auto-generated, please modify it to your needs } public function down(Schema $schema): void { // this down() migration is auto-generated, please modify it to your needs } }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

1	public function isTransactional(): bool { return false; }
2
3
4

1	public function getDescription(): string { return 'The description of my awesome migration!'; }
2
3
4

1	public function up(Schema $schema): void { $this->warnIf(true, 'Something might be going wrong'); // ... }
2
3
4
5
6

1	public function down(Schema $schema): void { $this->throwIrreversibleMigrationException(); // ... }
2
3
4
5
6

Maintained

Unmaintained