Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: 9f513fd305
Fetching contributors…

Cannot retrieve contributors at this time

287 lines (211 sloc) 10.5 kb

DoctrineMigrationsBundle

The database migrations feature is an extension of the database abstraction layer and offers you the ability to programmatically deploy new versions of your database schema in a safe, easy and standardized way.

Tip

You can read more about the Doctrine Database Migrations on the project's documentation.

Installation

Doctrine migrations for Symfony are maintained in the DoctrineMigrationsBundle. Make sure you have both the doctrine-migrations and DoctrineMigrationsBundle libraries configured in your project. Follow these steps to install the libraries in the Symfony Standard distribution.

Add the following to deps. This will register the Migrations Bundle and the doctrine-migrations library as dependencies in your application:

[doctrine-migrations]
    git=http://github.com/doctrine/migrations.git

[DoctrineMigrationsBundle]
    git=http://github.com/doctrine/DoctrineMigrationsBundle.git
    target=/bundles/Doctrine/Bundle/MigrationsBundle

Update the vendor libraries:

$ php bin/vendors install

Next, ensure the new Doctrine\DBAL\Migrations namespace will be autoloaded via autoload.php. The new Migrations namespace must be placed above the Doctrine\\DBAL entry so that the autoloader looks inside the migrations directory for those classes:

// app/autoload.php
$loader->registerNamespaces(array(
    //...
    'Doctrine\\DBAL\\Migrations' => __DIR__.'/../vendor/doctrine-migrations/lib',
    'Doctrine\\DBAL'             => __DIR__.'/../vendor/doctrine-dbal/lib',
));

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

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        //...
        new Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle(),
    );
}

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.

Running Migrations during Deployment

Of course, the end goal of writing migrations is to be able to use them to reliably update your database structure when you deploy your application. By running the migrations locally (or on a beta server), you can ensure that the migrations work as you expect.

When you do finally deploy your application, you just need to remember to run the doctrine:migrations:migrate command. Internally, Doctrine creates a migration_versions table inside your database and tracks which migrations have been executed there. So, no matter how many migrations you've created and executed locally, when you run the command during deployment, Doctrine will know exactly which migrations it hasn't run yet by looking at the migration_versions table of your production database. Regardless of what server you're on, you can always safely run this command to execute only the migrations that haven't been run yet on that particular database.

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:

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.

Jump to Line
Something went wrong with that request. Please try again.