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 and standardized way.

Even though Doctrine has schema-tool commands to update the database schema, its suggested to use doctrine migrations when updating the production database. Schema-tool database drop and update commands which may harm the database, so the safe approach would be doctrine migrations for production servers.

Doctrine migration update database by comparing schema files and database, generates a migration file, then migrates schema changes to the database.

Following image depicts the process.

Doctrine migration

Doctrine Migrations Setup

In order to use migrations we need to do the initial setup. There are two ways to install Doctrine migrations.

  1. Use as a supplement to already existing Doctrine setup
  2. Use as a standalone PHP Binary (PHAR)

As a supplement

1.    Get the sources from the GitHub repository either by downloading them, checking them out as SVN external or a Git submodule. Let’s download it by adding “doctrine/migrations”: “dev-master” to compose and update it

2.    Create console.php at the root of the project directory and add following stuffs to it

  • Setup a class loader to load the DoctrineDBALMigrations namespace into the project
use DoctrineCommonClassLoader;  
      $classLoader = new ClassLoader('DoctrineDBALMigrations', '/path/to/migrations/lib '); 
       // Usually path will be /vendor/doctrine/migrations/lib 
$classLoader->register();
  • Register migration console commands
$cli->addCommands(array(    
      // Migrations Commands  
        new DoctrineDBALMigrationsToolsConsoleCommandDiffCommand(),   
         new DoctrineDBALMigrationsToolsConsoleCommandExecuteCommand(), 
            new DoctrineDBALMigrationsToolsConsoleCommandGenerateCommand(), 
               new DoctrineDBALMigrationsToolsConsoleCommandMigrateCommand(),  
                 new DoctrineDBALMigrationsToolsConsoleCommandStatusCommand(), 
                    new DoctrineDBALMigrationsToolsConsoleCommandVersionCommand() ));
  •  Add ‘entity manager’, ‘database’ and ‘dialog’ helpers
//add bootstrap file for database connection and for metadata
       use bootstrap as bootstrapConfig;
        $bootstrapConfig = new bootstrapConfig(); 
$db = $bootstrapConfig->entityManager->getConnection(); 
$helperSet = new SymfonyComponentConsoleHelperHelperSet(array( 
     'em' => new DoctrineORMToolsConsoleHelperEntityManagerHelper($bootstrapConfig->entityManager),  
       'db' => new DoctrineDBALToolsConsoleHelperConnectionHelper($db),  
         'dialog' => new SymfonyComponentConsoleHelperDialogHelper() ));

 

$cli = new SymfonyComponentConsoleApplication('Doctrine Migrations', DoctrineDBALMigrationsMigrationsVersion::VERSION); 
      $cli->setCatchExceptions(true); 
      $cli->setHelperSet($helperSet);

3.  Configuration:  create /migrations/classes/DoctrineMigrations  root of the project directory and create migrations.xml or migrations.yml at the root of project and add path of migrations classes

name: Doctrine Sandbox Migrations
     migrations_namespace: DoctrineMigrations 
     table_name: doctrine_migration_versions 
     migrations_directory: /migrations/classes/DoctrineMigrations

After all the above setup we can check it by running the following command

php console.php list migrations

The above command should list migrations namespace usage.

As a standalone PHAR

1.    Download the Migrations PHP Binary, which is a standalone PHAR package file with all the required dependencies. Drop the file onto the project
2.    Create a batch script to register a system command for the migrations 

#!/bin/sh 
    php /path/to/doctrine-migrations.phar "$@"

3.    As PHAR file is standalone file and expects db configuration parameters to be passed. Create migrations-db.php and add db configurations parameters

//migrations-db.php 
    return array(  
          'driver'    => 'pdo_mysql',   
           'host'      => 'myDbHostIP',   
            'user'      => 'migrations', 
               'Password'  => 'password',  
                 'dbname'    => 'myAppDb'       );

 4.    At last add migrations.xml or migrations.yml

We shall be coming up with a Part 2 to this series, wherein we discuss the some other aspects involved in doctrine migrations such as the generate function, status function etc.