Yii Framework Offizieller Leitfaden zur Serie Ergänzung 27 – Arbeiten mit Datenbanken: Datenbankmigration

Hinweis: Yii unterstützt die Datenbankmigrationsfunktion erst ab Version 1.1.6.

Wie der Quellcode wächst auch die Struktur der Datenbank weiter, während wir datenbankgesteuerte Anwendungen entwickeln und pflegen. Beispielsweise möchten wir möglicherweise während der Entwicklung oder nach der Bereitstellung der Anwendung eine neue Tabelle hinzufügen In der Produktion stellen wir möglicherweise fest, dass wir einen Index für eine bestimmte Spalte hinzufügen müssen. Das Verfolgen dieser Änderungen an der Datenbankstruktur (Migrationen genannt) ist genauso wichtig wie das Betreiben des Quellcodes. Das System kann unterbrochen sein. Aus diesem Grund stellt das Yii-Framework Datenbankmigrationstools bereit, um den Datenbankmigrationsverlauf zu verfolgen, neue Migrationen anzuwenden oder alte Migrationen wiederherzustellen.

Die folgenden Schritte zeigen, wie Datenbankmigrationen während der Entwicklung verwendet werden:
Tim fügt eine neue Migration hinzu (z. B. eine neue Tabelle erstellen)
Tim übermittelt eine neue Migration an das Versionskontrolltool (z. B. SVN, GIT)
Doug aktualisiert das Versionskontrolltool und nimmt eine neue Migration heraus
Doug wendet neue Migrationen auf die lokale Entwicklungsversion der Datenbank an

Das Yii-Framework unterstützt die Datenbankmigration über das Befehlszeilentool yiic migrate. Dieses Tool unterstützt das Erstellen neuer Migrationen, das Anwenden/Rückgängigmachen/Abbrechen von Migrationen und das Anzeigen von Migrationen Historische und neue Migrationen.

Als nächstes beschreiben wir die Verwendung dieses Tools.

Hinweis: Bei der Migration mit dem Befehlszeilen-Migrationstool ist es am besten, yiic im Anwendungsverzeichnis (z. B. cd path/to/protected) anstelle des Systemverzeichnisses zu verwenden dass es zugänglich ist. Überprüfen Sie außerdem, ob die Datenbankverbindung in protected/config/console.php konfiguriert ist.

1. Erstellen Sie eine Migration

Wenn Sie eine neue Migration erstellen möchten (z. B. eine Nachrichtentabelle erstellen), können wir den folgenden Befehl ausführen:

yiic migrate create <name>

Der Parametername ist erforderlich und gibt eine sehr kurze Beschreibung dieser Migration an (z. B. create_news_table). Wie wir weiter unten zeigen werden, ist der Parameter name Teil des PHP-Klassennamens. Und es darf nur Buchstaben, Zahlen und Unterstriche enthalten.

yiic migrate create create_news_table

Der obige Befehl erstellt eine neue Datei mit dem Namen m101129_185401_create_news_table.php unter dem Pfad protected/migrations. Die Datei enthält den folgenden Code:

class m101129_185401_create_news_table extends CDbMigration
{
    public function up(){}

    public function down()
    {
        echo "m101129_185401_create_news_table does not support migration down.\n";
        return false;
    }

    /*
    // implement safeUp/safeDown instead if transaction is needed
    public function safeUp(){}

    public function safeDown(){}
    */
}

Beachten Sie dies: Den Klassennamen und Der Dateiname ist derselbe, beide sind m_, wobei den UTC-Zeitstempel darstellt, als die Migration erstellt wurde (im Format yymmdd_hhmmss), und benannter Parameter des Befehls von.

Die up()-Methode sollte den Code zum Implementieren der Datenbankmigration enthalten, während die down()-Methode Code zum Wiederherstellen der Vorgänge in der up()-Methode enthält.

Manchmal ist es nicht möglich, die Operationen in down() zu implementieren. Wenn beispielsweise eine Zeile der Tabelle in der up()-Methode gelöscht wird, kann sie in der down-Methode nicht wiederhergestellt werden. In diesem Fall wird die Migration als irreversibel bezeichnet, was bedeutet, dass wir nicht zum vorherigen Zustand der Datenbank zurückkehren können. Im oben generierten Code gibt die down()-Methode „false“ zurück, um anzuzeigen, dass die Migration irreversibel ist.

Info: Ab Version 1.1.7 werden alle unten aufgeführten Migrationen abgebrochen, wenn die Methode up() oder down() false zurückgibt. In Version 1.1.6 muss eine Ausnahme ausgelöst werden, um die folgende Migration abzubrechen.

Lassen Sie uns anhand eines Beispiels die Migration der Erstellung einer Nachrichtentabelle zeigen

class m101129_185401_create_news_table extends CDbMigration
{
    public function up()
    {
        $this->createTable('tbl_news', array(
            'id' => 'pk',
            'title' => 'string NOT NULL',
            'content' => 'text',
        ));
    }

    public function down()
    {
        $this->dropTable('tbl_news');
    }
}

Die Basisklasse CDbMigration bietet eine Reihe von Methoden zum Betreiben von Daten und Datenbanken, zum Beispiel CDbMigration: :createTable Eine Datenbanktabelle wird erstellt und CDbMigration::insert fügt eine Datenzeile ein. Diese Methoden verwenden alle die von CDbMigration::getDbConnection() zurückgegebene Datenbankverbindung, die standardmäßig Yii::app()->db ist.

Info: Möglicherweise stellen Sie fest, dass die von CDbMigration bereitgestellten Datenbankmethoden denen in CDbCommand sehr ähnlich sind. Tatsächlich sind sie grundsätzlich gleich, außer dass die CDbMigration-Methode die für die Ausführung benötigte Zeit berechnet und einige Informationen zu den Methodenparametern ausgibt.

Sie können auch die Methode zum Betreiben der Datenbank erweitern, wie zum Beispiel:

public function up()
{
    $sql = "CREATE TABLE IF NOT EXISTS user(
        id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
        username VARCHAR(32) NOT NULL,
        password VARCHAR(32) NOT NULL,
        email VARCHAR(32) NOT NULL
    ) ENGINE=MyISAM";
    $this->createTableBySql('user',$sql);
}
public function createTableBySql($table,$sql){
    echo " > create table $table ...";
    $time=microtime(true);
    $this->getDbConnection()->createCommand($sql)->execute();
    echo " done (time: ".sprintf('%.3f', microtime(true)-$time)."s)\n";
}

2. Transaktionsmigration

Info: Die Funktion der Transaktionsmigration wird ab unterstützt Version 1.1.7.

Bei komplexen Datenbankmigrationen möchten wir oft sicherstellen, dass jede Migration erfolgreich ist oder fehlschlägt, damit die Datenbank Konsistenz und Integrität behält. Um dieses Ziel zu erreichen, können wir Datenbanktransaktionen nutzen.

Wir können Datenbanktransaktionen explizit aktivieren und anderen datenbankbezogenen transaktionshaltigen Code anhängen, zum Beispiel:

class m101129_185401_create_news_table extends CDbMigration
{
    public function up()
    {
        $transaction=$this->getDbConnection()->beginTransaction();
        try
        {
            $this->createTable('tbl_news', array(
                'id' => 'pk',
                'title' => 'string NOT NULL',
                'content' => 'text',
            ));
            $transaction->commit();
        }catch(Exception $e){
            echo "Exception: ".$e->getMessage()."\n";
            $transaction->rollback();
            return false;
        }
    }

    // ...similar code for down()
}

Allerdings a mehr Eine einfache Möglichkeit, Transaktionsunterstützung zu erhalten, besteht darin, die Methode „safeUp()“ als Ersatz für „up()“ und „safeDown()“ als Ersatz für „down()“ zu implementieren:

class m101129_185401_create_news_table extends CDbMigration
{
    public function safeUp()
    {
        $this->createTable('tbl_news', array(
            'id' => 'pk',
            'title' => 'string NOT NULL',
            'content' => 'text',
        ));
    }

    public function safeDown()
    {
        $this->dropTable('tbl_news');
    }
}

Wenn Yii eine Migration durchführt, wird es wird aktiviert. Die Datenbankmigration ruft dann „safeUp()“ oder „safeDown()“ auf. Wenn in „safeUp()“ und „safeDown()“ Fehler auftreten, wird die Transaktion zurückgesetzt, um sicherzustellen, dass die Datenbank Konsistenz und Integrität beibehält.

Hinweis: Nicht alle DBMS unterstützen Transaktionen. In diesem Fall müssen Sie stattdessen up() und down() implementieren.

3. Migrationen verwenden

Um alle gültigen neuen Migrationen zu verwenden (d. h. die lokale Datenbank auf den neuesten Stand zu bringen), führen Sie den folgenden Befehl aus:

yiic migrate

这个命令会显示所有新迁移的列表. 如果你确定使用迁移, 它将会在每一个新的迁移类中运行up()方法, 一个接着一个, 按照类名中的时间戳的顺序.

在使用迁移之后, 迁移工具会在一个数据表tbl_migration中写一条记录——允许工具识别应用了哪一个迁移. 如果tbl_migration表不存在 ，工具会在配置文件中db指定的数据库中自动创建。

有时候, 我们可能指向应用一条或者几条迁移. 那么可以运行如下命令:

yiic migrate up 3

这个命令会运行3个新的迁移. 该表value的值3将允许我们改变将要被应用的迁移的数目。

我们还可以通过如下命令迁移数据库到一个指定的版本:

yiic migrate to 101129_185401

也就是我们使用数据库迁移名中的时间戳部分来指定我们想要迁移到的数据库的版本。如果在最后应用的数据库迁移和指定的迁移之间有多个迁移, 所有这些迁移都会被应用. 如果指定迁移已经使用过了, 所有之后应用的迁移都会恢复。

4. 恢复迁移

想要恢复最后一个或几个已应用的迁移，我们可以运行如下命令：

yiic migrate down [step]

其中选项 step 参数指定了要恢复的迁移的数目. 默认是1, 意味着恢复最后一个应用的迁移.

正如我们之前所描述的, 不是所有的迁移都能恢复. 尝试恢复这种迁移会抛出异常并停止整个恢复进程。

5. 重做迁移

重做迁移意味着第一次恢复并且之后应用指定的迁移. 这个可以通过如下命令来实现:

yiic migrate redo [step]

其中可选的step参数指定了重做多少个迁移 . 默认是1, 意味着重做最后一个迁移.

6. 显示迁移信息

除了应用和恢复迁移之外, 迁移工具还可以显示迁移历史和被应用的新迁移。

yiic migrate history [limit]
yiic migrate new [limit]

其中可选的参数 limit 指定克显示的迁移的数目。如果limit没有被指定，所有的有效迁移都会被显示。

第一个命令显示已经被应用的迁移, 而第二个命令显示还没被应用的迁移。

7. 编辑迁移历史

有时候, 我们可能想要在没有应用和恢复相应迁移的时候编辑迁移历史来指定迁移版本. 这通常发生在开发一个新的迁移的时候. 我们使用下面的命令来实现这一目标.

yiic migrate mark 101129_185401

这个命令和yiic migrate to命令非常类似, 但它仅仅只是编辑迁移历史表到指定版本而没有应用或者恢复迁移。

8. 自定义迁移命令

有多种方式来自定义迁移命令。

使用命令行选项

迁移命令需要在命令行中指定四个选项:

interactive: boolean, specifies whether to perform migrations in an interactive mode. Defaults to true, meaning the user will be prompted when performing a 
specific migration. You may set this to false should the migrations be done in a background process.

migrationPath: string, specifies the directory storing all migration class files. This must be specified in terms of a path alias, and the corresponding 
directory must exist. If not specified, it will use the migrations sub-directory under the application base path.

migrationTable: string, specifies the name of the database table for storing migration history information. It defaults to tbl_migration. The table 
structure is version varchar(255) primary key, apply_time integer.

connectionID: string, specifies the ID of the database application component. Defaults to 'db'.

templateFile: string, specifies the path of the file to be served as the code template for generating the migration classes. This must be specified in terms of a 
path alias (e.g. application.migrations.template). If not set, an internal template will be used. Inside the template, the token {ClassName} will be replaced 
with the actual migration class name.

想要指定这些选项, 使用如下格式的迁移命令执行即可：

yiic migrate up --option1=value1 --option2=value2 ...

例如, 如果我们想要迁移一个论坛模块，它的迁移文件都放在模块的迁移文件夹中，可以使用如下命令:

yiic migrate up --migrationPath=ext.forum.migrations

注意在你设置布尔选项如interactive的时候，使用如下方式传入1或者0到命令行:

yiic migrate --interactive=0

配置全局命令

命令行选项允许我们快速配置迁移命令, 但有时候我们可能想要只配置一次命令. 例如, 我们可能想要使用不同的表来保存迁移历史, 或者我们想要使用自定义的迁移模板。我们可以通过编辑控制台应用的配置文件来实现，如下所示:

return array(
    ......
    'commandMap'=>array(
        'migrate'=>array(
            'class'=>'system.cli.commands.MigrateCommand',
            'migrationPath'=>'application.migrations',
            'migrationTable'=>'tbl_migration',
            'connectionID'=>'db',
            'templateFile'=>'application.migrations.template',
        ),
        ......
    ),
    ......
);

现在如果我们运行迁移命令，上述配置将会生效，而不需要我们每一次在命令行中都输入那么多选项信息。

以上就是Yii框架官方指南系列增补版27——使用数据库：数据库迁移的内容，更多相关内容请关注PHP中文网（www.php.cn）！