The symfony and Doctrine book

A common problem in web development is how to manage changes to your database as your models evolve and schema changes. The migrations support in Doctrine provides an efficient solution to this problem.

sfDoctrinePlugin implements some additional tasks for generating migration classes both from existing databases and models. You can also use Doctrine to generate your blank skeleton migration classes.

Available Migration Tasks

:generate-migration          Generate migration class (doctrine-generate-migration)
:generate-migrations-db      Generate migration classes from existing database connections (doctrine-generate-migrations-db, doctrine-gen-migrations-from-db)
:generate-migrations-models  Generate migration classes from an existing set of models (doctrine-generate-migrations-models, doctrine-gen-migrations-from-models)
:migrate                     Migrates database to current/specified version (doctrine-migrate)

The examples in this chapter assume you are working with the following schema and data fixtures. We'll use this as the base of all the examples documented here.

Starting Schema and Data Fixtures

project/config/doctrine/schema.yml

BlogPost:
  actAs:
    I18n:
      fields: [title, body]
    Timestampable:
  columns:
    author: string(255)
    title: string(255)
    body: clob
  relations:
    Tags:
      class: Tag
      refClass: BlogPostTag
      foreignAlias: BlogPosts
Tag:
  columns:
    name: string(255)
BlogPostTag:
  columns:
    blog_post_id:
      type: integer
      primary: true
    tag_id:
      type: integer
      primary: true

project/data/fixtures.yml

BlogPost:
  BlogPost_1:
    author: Jonathan H. Wage
    Translation:
      en:
        title: Test Blog Post
        body: This is the body of the test blog post
    Tags: [php, orm]
Tag:
  php:
    name: PHP
  orm:
    name: ORM

Generating Migrations

Doctrine offers the ability to generate sets of migration classes for existing databases or existing models as well as generating blank migration classes for you to fill in with the code to make your schema changes.

From Database

If you have an existing database you can build a set of migration classes that will re-create your database by running the following command.

$ ./symfony doctrine:generate-migrations-db

From Models

If you have an existing set of models you can build a set of migration classes that will create your database by running the following command.

$ ./symfony doctrine:generate-migrations-models

Now that you have a set of migration classes you can reset your database and run the migrate command to re-create the database.

$ ./symfony doctrine:drop-db
$ ./symfony doctrine:build-db
$ ./symfony doctrine:migrate
$ ./symfony doctrine:data-load

Skeleton

Now that your database is created and migrated to the latest version you can generate new migration class skeletons to migrate your schema as your model evolves. Imagine you have a new column that needs to be added to the BlogPost model named excerpt. Below is the updated BlogPost schema which includes the new column.

BlogPost:
  actAs:
    I18n:
      fields: [title, body]
    Timestampable:
  columns:
    author: string(255)
    title: string(255)
    body: clob
    excerpt: string(255)
  relations:
    Tags:
      class: Tag
      refClass: BlogPostTag
      foreignAlias: BlogPosts

Now we need to generate the blank migration skeleton for adding the excerpt column to the database. Run the following command to generate the migration class.

$ ./symfony doctrine:generate-migration AddBlogPostExcerptColumn

Now in project/lib/migration/doctrine you will see a new file named 006_add_blog_post_excerpt_column.class.php with the following code in it.

/**
 * This class has been auto-generated by the Doctrine ORM Framework
 */
class AddBlogPostExcerptColumn extends Doctrine_Migration
{
    public function up()
    {
 
    }
 
    public function down()
    {
 
    }
}

Each migration consists of an up() method and a down() method. Inside the up() is where you can add columns, create tables, etc. and the down() simply negates anything done in the up(). Each class essentially represents a version of your database and the up() and down() methods allow you to walk backwards and forwards between versions of your database.

Now lets write the code for our new migration class to add the excerpt column.

/**
 * This class has been auto-generated by the Doctrine ORM Framework
 */
class AddBlogPostExcerptColumn extends Doctrine_Migration
{
    public function up()
    {
      $this->addColumn('blog_post', 'excerpt', 'string', array('length' => '255'));
    }
 
    public function down()
    {
      $this->removeColumn('blog_post', 'excerpt');
    }
}

Now you can run the following command and it will upgrade your database to the latest version using the migration class we just wrote and the excerpt column will be added to the database.

$ ./symfony doctrine:migrate

More can be read about migrations in the Doctrine Manual here.