DoctrineMigrationsBundle

数据库迁移特征是数据库抽象层的扩展,允许你用编程的方式，安全、方便、标准化实现数据库结构的更新。

安装

首先使用composer安装

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

如果安装正确的话可以在vendor/doctrine/doctrine-migrations-bundle找到DoctrineMigrationsBundle。

然后在AppKernel.php里面加载DoctrineMigrationsBundle

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

配置

你可以在config.yml里面配置路径、命名空间、表名和名称。下例是默认值：

# app/config/config.yml
doctrine_migrations:
    dir_name: "%kernel.root_dir%/DoctrineMigrations"
    namespace: Application\Migrations
    table_name: migration_versions
    name: Application Migrations

使用

所有Migration功能包含一些控制台命令

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.

使用status命令获取你的migration状态

app/console doctrine:migrations:status

 == Configuration

    >> Name:                                               Application Migrations
    >> Database Driver:                                    pdo_mysql
    >> Database Name:                                      tech-edu
    >> Configuration Source:                               manually configured
    >> Version Table Name:                                 migration_versions
    >> Version Column Name:                                version
    >> Migrations Namespace:                               Application\Migrations
    >> Migrations Directory:                               /var/www/gitlab/XGC/app/DoctrineMigrations
    >> Previous Version:                                   Already at first version
    >> Current Version:                                    0
    >> Next Version:                                       Already at latest version
    >> Latest Version:                                     0
    >> Executed Migrations:                                0
    >> Executed Unavailable Migrations:                    0
    >> Available Migrations:                               0
    >> New Migrations:                                     0

现在，你可以开始使用migrations生成一个空的migration class，后面你将会知道doctrine是如何为你自动生成Migrations的

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

打开新生成的文件，你将会看到如下样子：

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)
    {

    }
}

现在再执行status命令你将会看到有一个新的migration可以执行

$ 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

之后你可以在up（） down（）里面添加migration 代码，最后使用migrate命令执行文件：

$ php app/console doctrine:migrations:migrate 20100621140655

如何书写migration代码请参考doctrine migration官方文档

在部署应用中使用migration

使用migration的最终目的是在你部署应用的时候能够更新你的数据库表结构。通过在本地环境下运行migration确保运行的结果是正确的。

在你部署应用的最后环节，你只需要运行doctrine:migrations:migrate命令。Doctrine在你的数据库里面创建了一张migration_versions表，记录了哪些migration被执行，因此不管你执行多少遍migrate命令，它都只会执行那些没有被执行过的migration文件。

跳过指定migration文件

运行下面命令将指定版本的migration文件添加进migration_versions表

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

这样在执行的时候就会忽略改文件了。

自动生成migrations

现实中，你应该很少需要手动写migrations，因为migrations库可以对比你的doctrine映射与实际表结构自动生成migration。

例如：你创建了一个新的用户实例并且在orm里面添加了映射

// 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;
}

有了这些信息，doctrine已经可以帮你把user对象和hello_user表持久化了。当然，表现在还不存在。用diff命令可以自动生成

$ php app/console doctrine:migrations:diff

你可以看到根据这两者的差异自动生成了一个migration class。里面有创建table_user表的sql语句，下一步只需要执行migrate指令

$ php app/console doctrine:migrations:migrate

所以，每当你改变了映射信息，你需要执行diff命令来生成migration class

假如你在项目最开始的时候就这样做的话，你就可以在任何时候使用migrate命令来获取到最干净的结构

你也可以通过下面的命令来跳过所有的migration

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

Container Aware Migrations

在某些情况下，您可能需要访问容器，以确保您的数据结构的正确更新。这可能在你创建一些有特殊逻辑的实体的时候会用到。

你可以加载ContainerAwareInterface来获取容器的访问

// ...
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
    }
}

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:

doctrine:
    dbal:
        schema_filter: ~^(?!t_)~

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.

（最后部分以后再看。。。。。。）