DoctrineMigrationsBundle

Installation

Doctrine migrations for Symfony are maintained in the DoctrineMigrationsBundle. The bundle uses external Doctrine Database Migrations library.

First, install the bundle with composer:

$ composer require doctrine/doctrine-migrations-bundle "^1.0"

If everything worked, the DoctrineMigrationsBundle can now be found at vendor/doctrine/doctrine-migrations-bundle.

Finally, be sure to enable the bundle in AppKernel.php by including the following:

1
// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        //...
        new Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle(),
    );
}
2
3
4
5
6
7
8

Configuration

You can configure the path, namespace, table_name, name, organize_migrations and custom_template in your config.yml. The examples below are the default values.

1
# app/config/config.yml
doctrine_migrations:
    dir_name: "%kernel.root_dir%/DoctrineMigrations"
    namespace: Application\Migrations
    table_name: migration_versions
    name: Application Migrations
    organize_migrations: false # Version >= 1.2, possible values are: "BY_YEAR", "BY_YEAR_AND_MONTH", false
    custom_template: ~ # Version >= 1.2, path to your custom migrations template
2
3
4
5
6
7
8

Usage

All of the migrations functionality is contained in a few console commands:

doctrine:migrations
  :diff     Generate a migration by comparing your current database to your mapping information.
  :execute  Execute a single migration version up or down manually.
  :generate Generate a blank migration class.
  :migrate  Execute a migration to a specified version or the latest available version.
  :status   View the status of a set of migrations.
  :version  Manually add and delete migration versions from the version table.

Start by getting the status of migrations in your application by running the status command:

php app/console doctrine:migrations:status

 == Configuration

    >> Name:                                               Application Migrations
    >> Configuration Source:                               manually configured
    >> Version Table Name:                                 migration_versions
    >> Migrations Namespace:                               Application\Migrations
    >> Migrations Directory:                               /path/to/project/app/DoctrineMigrations
    >> Current Version:                                    0
    >> Latest Version:                                     0
    >> Executed Migrations:                                0
    >> Available Migrations:                               0
    >> New Migrations:                                     0

Now, you can start working with migrations by generating a new blank migration class. Later, you'll learn how Doctrine can generate migrations automatically for you.

$ php app/console doctrine:migrations:generate
Generated new migration class to "/path/to/project/app/DoctrineMigrations/Version20100621140655.php"

Have a look at the newly generated migration class and you will see something like the following:

namespace Application\Migrations;

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

class Version20100621140655 extends AbstractMigration
{
    public function up(Schema $schema)
    {

    }

    public function down(Schema $schema)
    {

    }
}

If you run the status command it will now show that you have one new migration to execute:

$ php app/console doctrine:migrations:status --show-versions

 == Configuration

   >> Name:                                               Application Migrations
   >> Configuration Source:                               manually configured
   >> Version Table Name:                                 migration_versions
   >> Migrations Namespace:                               Application\Migrations
   >> Migrations Directory:                               /path/to/project/app/DoctrineMigrations
   >> Current Version:                                    0
   >> Latest Version:                                     2010-06-21 14:06:55 (20100621140655)
   >> Executed Migrations:                                0
   >> Available Migrations:                               1
   >> New Migrations:                                     1

== Migration Versions

   >> 2010-06-21 14:06:55 (20100621140655)                not migrated

Now you can add some migration code to the up() and down() methods and finally migrate when you're ready:

$ php app/console doctrine:migrations:migrate 20100621140655

For more information on how to write the migrations themselves (i.e. how to fill in the up() and down() methods), see the official Doctrine Migrations documentation.

$ php app/console doctrine:migrations:version YYYYMMDDHHMMSS --add

Generating Migrations Automatically

In reality, you should rarely need to write migrations manually, as the migrations library can generate migration classes automatically by comparing your Doctrine mapping information (i.e. what your database should look like) with your actual current database structure.

For example, suppose you create a new User entity and add mapping information for Doctrine's ORM:

1
// src/Acme/HelloBundle/Entity/User.php
namespace Acme\HelloBundle\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="hello_user")
 */
class User
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

    /**
     * @ORM\Column(type="string", length=255)
     */
    protected $name;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

1
# src/Acme/HelloBundle/Resources/config/doctrine/User.orm.yml
Acme\HelloBundle\Entity\User:
    type: entity
    table: hello_user
    id:
        id:
            type: integer
            generator:
                strategy: AUTO
    fields:
        name:
            type: string
            length: 255
2
3
4
5
6
7
8
9
10
11
12
13

1
<!-- src/Acme/HelloBundle/Resources/config/doctrine/User.orm.xml -->
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                    http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">

    <entity name="Acme\HelloBundle\Entity\User" table="hello_user">
        <id name="id" type="integer" column="id">
            <generator strategy="AUTO"/>
        </id>
        <field name="name" column="name" type="string" length="255" />
    </entity>

</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13
14

With this information, Doctrine is now ready to help you persist your new User object to and from the hello_user table. Of course, this table doesn't exist yet! Generate a new migration for this table automatically by running the following command:

$ php app/console doctrine:migrations:diff

You should see a message that a new migration class was generated based on the schema differences. If you open this file, you'll find that it has the SQL code needed to create the hello_user table. Next, run the migration to add the table to your database:

$ php app/console doctrine:migrations:migrate

The moral of the story is this: after each change you make to your Doctrine mapping information, run the doctrine:migrations:diff command to automatically generate your migration classes.

If you do this from the very beginning of your project (i.e. so that even the first tables were loaded via a migration class), you'll always be able to create a fresh database and run your migrations in order to get your database schema fully up to date. In fact, this is an easy and dependable workflow for your project.

If you don't want to use this workflow and instead create your schema via doctrine:schema:create, you can tell Doctrine to skip all existing migrations:

$ php app/console doctrine:migrations:version --add --all

Otherwise Doctrine will try to run all migrations, which probably will not work.

Container Aware Migrations

In some cases you might need access to the container to ensure the proper update of your data structure. This could be necessary to update relations with some specific logic or to create new entities.

Therefore you can just implement the ContainerAwareInterface with its needed methods to get full access to the container or ContainerAwareTrait if you use Symfony >= 2.4.

1
// ...
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

class Version20130326212938 extends AbstractMigration implements ContainerAwareInterface
{
    private $container;

    public function setContainer(ContainerInterface $container = null)
    {
        $this->container = $container;
    }

    public function up(Schema $schema)
    {
        // ... migration content
    }

    public function postUp(Schema $schema)
    {
        $converter = $this->container->get('my_service.convert_data_to');
        // ... convert the data from markdown to html for instance
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

With the trait

1
// ...
use Symfony\Component\DependencyInjection\ContainerAwareInterface;
use Symfony\Component\DependencyInjection\ContainerAwareTrait;

class Version20130326212938 extends AbstractMigration implements ContainerAwareInterface
{
    use ContainerAwareTrait;

    public function up(Schema $schema)
    {
        // ... migration content
    }

    public function postUp(Schema $schema)
    {
        $converter = $this->container->get('my_service.convert_data_to');
        // ... convert the data from markdown to html for instance
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Manual Tables

It is a common use case, that in addition to your generated database structure based on your doctrine entities you might need custom tables. By default such tables will be removed by the doctrine:migrations:diff command.

If you follow a specific scheme you can configure doctrine/dbal to ignore those tables. Let's say all custom tables will be prefixed by t_. In this case you just have to add the following configuration option to your doctrine configuration:

1
doctrine:
    dbal:
        schema_filter: ~^(?!t_)~
2
3

1
<doctrine:dbal schema-filter="~^(?!t_)~" ... />

1
$container->loadFromExtension('doctrine', array(
    'dbal' => array(
        'schema_filter'  => '~^(?!t_)~',
        // ...
    ),
    // ...
));
2
3
4
5
6
7

This ignores the tables on the DBAL level and they will be ignored by the diff command.

Note that if you have multiple connections configured then the schema_filter configuration will need to be placed per-connection.