Doctrine Migration – Part 2

Doctrine migration has been used by me many times, and there are some small changes which affect the process, and some others which help us to use the migration process better.  Part 1 of the Doctrine migration series depicted how to go about a migration set up. Now, I shall go about explaining in a step by step manner how to go about using doctrine migrations.

Using Doctrine Migrations

1. Migration generate

php console.php migrations:generate
The command generates blank migration class in migrations/classes/DoctrineMigrations with latest version. Have a look and the class will look as below:

namespace DoctrineMigrations;

use DoctrineDBALMigrationsAbstractMigration,
 DoctrineDBALSchemaSchema;

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

 }

 public function down(Schema $schema)
 {

 }
}

Doctrine has addSql() method to add our own custom SQL queries.

For example

namespace DoctrineMigrations;

use DoctrineDBALMigrationsAbstractMigration,
 DoctrineDBALSchemaSchema;

class Version20100416130422 extends AbstractMigration
{
 public function up(Schema $schema)
 {
 $this->addSql('CREATE TABLE addresses (id INT NOT NULL, street VARCHAR(255) NOT NULL, PRIMARY KEY(id)) ENGINE = InnoDB');
 }

 public function down(Schema $schema)
 {
 $this->addSql('DROP TABLE addresses');
 }
}

2. Migration status

php console.php migrations:status
The command allows to View the status of a set of migrations.

Now that we have a new migration class present, lets run the status task to check if it exists.

$ ./doctrine migrations:status

 == Configuration

    >> Name:                                    Doctrine Sandbox Migrations
    >> Database Driver:                 pdo_mysql
    >> Database Name:                 testdb
    >> Configuration Source:       /Users/jwage/Sites/doctrine2git/tools/sandbox/migrations.xml
    >> Version Table Name:         doctrine_migration_versions
    >> Migrations Namespace:    DoctrineMigrations
    >> Migrations Directory:        /Users/jwage/Sites/doctrine2git/tools/sandbox/DoctrineMigrations
    >> Current Version:                 2010-04-16 13:04:22 (20100416130422)
    >> Latest Version:                    2010-04-16 13:04:22 (20100416130422)
    >> Executed Migrations:        0
    >> Available Migrations:        1
    >> New Migrations:                1

 == Migration Versions

    >> 2010-04-16 13:04:01 (20100416130401)                not migrated

We can see a new version present and ready to be executed.

3. Migration migrate

php console.php migrations:migrate

The command executes a migration to a specified version or the latest available version. Now we are ready to give it a test!

First lets just do a dry-run to make sure it produces the SQL we expect:

$ php console.php migrations:migrate --dry-run
Are you sure you wish to continue?
y
Executing dry run of migration up to 20100416130452 from 0

  >> migrating 20100416130452

     -> CREATE TABLE users (username VARCHAR(255) NOT NULL, password VARCHAR(255) NOT NULL) ENGINE = InnoDB

Now, everything looks good so we can remove the –dry-run option and actually execute the migration.

$ php console.php migrations:migrate
Are you sure you wish to continue?
y
Migrating up to 20100416130452 from 0

  >> migrating 20100416130452

     -> CREATE TABLE users (username VARCHAR(255) NOT NULL, password VARCHAR(255) NOT NULL) ENGINE = InnoDB

  >> migrated

By checking the status again we should see everything is updated.

4. Migration diff

The command generates a migration by comparing project current database to mapping information. Doctrine 2 ORM provides this command to generate migration classes by changing entity mappings instead of manually adding modifications to migration class.

Lets add a new “test” column to User entity.

namespace Entities;

/** @Entity @Table(name="users") */
class User
{
 /**
 * @var string $test
 */
 private $test;

 // ...
}

Now by running the diff command, migration class will be generated with the changes required to update the database!

5. Reverting Migrations

You might have noticed in the previous examples that we defined a down() method which drops the addresses table that we created. This method allows us to easily revert changes the schema has been migrated to. The migrate command takes a version argument which you can use to roll back your schema to a specific version of your migrations.

$ php console.php migrations:migrate 0
Are you sure you wish to continue?
y
Migrating down to 0 from 20100416130422

  -- reverting 20100416130422

     -> DROP TABLE addresses

  -- reverted

  -- reverting 20100416130401

     -> DROP TABLE users

  -- reverted

6. Writing Migration SQL Files

Doctrine migrations provide to choose not to execute a migration directly on a database and instead output all the SQL statements to a file. This is possible by using the –write-sql option of the migrate command:

php console.php migrations:migrate –write-sql

Steps to follow

So, let us look back the steps involved in a doctrine migration.

    1. Change Your schema.yml
    2. Create Migration File (php console.php migrations:diff)
    3. Run migration dry run (php console.php migrations:migrate –dry-run)
    4. If everything is fine then run Migration (php console.php migrations:migrate)

On local, follow all above steps and then commit the changes to SVN, follow 3 and 4 steps on production to migrate the schema changes.

The following two tabs change content below.

Swapna Vijaykumar

Studied to be an engineer, can tickle your taste buds, believes in free technology and working on creepy open source

Latest posts by Swapna Vijaykumar (see all)

Swapna Vijaykumar

Studied to be an engineer, can tickle your taste buds, believes in free technology and working on creepy open source

All stories by: Swapna Vijaykumar