Migrations¶

シンタックス¶

以下の bake コマンドは、 products テーブルを追加するためのマイグレーションファイルを 作成します。 :

bin/cake bake migration CreateProducts name:string description:text created modified

あなたのデータベースにテーブルの作成、カラムの追加などをするために bake を使用する場合、 一般に以下の２点を指定します。

• あなたが生成するマイグレーションの名前 (例えば、 CreateProducts)

• マイグレーションで追加や削除を行うテーブルのカラム (例えば、 name:string description:text created modified)

規約のために、すべてのスキーマの変更がこれらのシェルコマンドで動作するわけではありません。

さらに、実行内容を完全に制御したいのであれば、空のマイグレーションファイルを 作る事ができます。

bin/cake migrations create MyCustomMigration

fieldName:fieldType?[length]:indexType:indexName

テーブルの作成¶

テーブルを作成するために bake が使えます。 :

bin/cake bake migration CreateProducts name:string description:text created modified

上記のコマンドラインは、よく似たマイグレーションファイルを生成します。

<?php
use Migrations\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /**
     * Change Method.
     *
     * More information on this method is available here:
     * https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     * @return void
     */
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string', [
            'default' => null,
            'limit' => 255,
            'null' => false,
        ]);
        $table->addColumn('description', 'text', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('created', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('modified', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->create();
    }
}

既存のテーブルにカラムを追加¶

もしコマンドラインのマイグレーション名が "AddXXXToYYY" といった 書式で、その後にカラム名と型が続けば、カラムの追加を行うコードを含んだ マイグレーションファイルが生成されます。 :

bin/cake bake migration AddPriceToProducts price:decimal

コマンドラインを実行すると下記のようなファイルが生成されます。

<?php
use Migrations\AbstractMigration;

class AddPriceToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('price', 'decimal')
              ->update();
    }
}

テーブルにインデックスとしてカラムを追加¶

カラムにインデックスを追加することも可能です。 :

bin/cake bake migration AddNameIndexToProducts name:string:index

このようなファイルが生成されます。

<?php
use Migrations\AbstractMigration;

class AddNameIndexToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string')
              ->addIndex(['name'])
              ->update();
    }
}

フィールド長を指定¶

もし、フィールド長を指定する必要がある場合、フィールドタイプにカギ括弧の中で指定できます。例:

bin/cake bake migration AddFullDescriptionToProducts full_description:string[60]

上記のコマンドラインを実行すると生成されます。

<?php
use Migrations\AbstractMigration;

class AddFullDescriptionToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('full_description', 'string', [
            'default' => null,
            'limit' => 60,
            'null' => false,
        ])
        ->update();
    }
}

長さが未指定の場合、いくつかのカラム型の長さは初期値が設定されます。

• string: 255

• integer: 11

• biginteger: 20

テーブルから列を変更する¶

同様に、移行名が「AlterXXXOnYYY」の形式の場合、コマンドラインを使用して、列を変更する移行を生成できます。

bin/cake bake migration AlterPriceOnProducts name:float

生成されます:

<?php
use Migrations\AbstractMigration;

class AlterPriceFromProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->changeColumn('name', 'float');
        $table->update();
    }
}

テーブルからカラムを削除¶

もしマイグレーション名が "RemoveXXXFromYYY" であるなら、同様にコマンドラインを使用して、 カラム削除のマイグレーションファイルを生成することができます。 :

bin/cake bake migration RemovePriceFromProducts price

このようなファイルが生成されます。

<?php
use Migrations\AbstractMigration;

class RemovePriceFromProducts extends AbstractMigration
{
    public function up()
    {
        $table = $this->table('products');
        $table->removeColumn('price')
              ->save();
    }
}

既存のデータベースからマイグレーションファイルを作成する¶

もしあなたが既存のデータベースで、マイグレーションの使用を始めたい場合や、 あなたのアプリケーションのデータベースで初期状態のスキーマのバージョン管理を 行いたい場合、 migration_snapshot コマンドを実行します。 :

bin/cake bake migration_snapshot Initial

これはデータベース内のすべてのテーブルの create 文を含んだ YYYYMMDDHHMMSS_Initial.php と呼ばれるマイグレーションファイルを生成します。

デフォルトで、スナップショットは、 default 接続設定で定義されたデータベースに 接続することによって作成されます。 もし、異なるデータベースからスナップショットを bake する必要があるなら、 --connection オプションが使用できます。 :

bin/cake bake migration_snapshot Initial --connection my_other_connection

--require-table フラグを使用することによって対応するモデルクラスを定義したテーブルだけを 含まれることを確認することができます。 :

bin/cake bake migration_snapshot Initial --require-table

--require-table フラグを使用した時、シェルは、あなたのアプリケーションを通して Table クラスを見つけて、スナップショットのモデルテーブルのみ追加します。

プラグインのためのスナップショットを bake したい場合、同じロジックが暗黙的に適用されます。 そうするために、 --plugin オプションを使用する必要があります。 :

bin/cake bake migration_snapshot Initial --plugin MyPlugin

定義された Table オブジェクトモデルを持つテーブルだけプラグインのスナップショットに 追加されます。

スナップショットを bake した時、phinx のログテーブルに自動的に追加されることに注意してください。

migrate : マイグレーションを適用する¶

マイグレーションファイルを生成したり記述したら、以下のコマンドを実行して 変更をデータベースに適用しましょう。 :

# マイグレーションをすべて実行
bin/cake migrations migrate

# 特定のバージョンに移行するためには、 ``--target`` オプション
# （省略形は ``-t`` ）を使用します。
# これはマイグレーションファイル名の前に付加されるタイムスタンプに対応しています。
bin/cake migrations migrate -t 20150103081132

# デフォルトで、マイグレーションファイルは、 **config/Migrations** ディレクトリーに
# あります。 ``--source`` オプション (省略形は ``-s``) を使用することで、
# ディレクトリーを指定できます。
# 次の例は、 **config/Alternate** ディレクトリー内でマイグレーションを実行します。
bin/cake migrations migrate -s Alternate

# ``--connection`` オプション (省略形は ``-c``) を使用することで
# ``default`` とは異なる接続でマイグレーションを実行できます。
bin/cake migrations migrate -c my_custom_connection

# マイグレーションは、プラグインのためにも実行できます。 ``--plugin`` オプション
# (省略形は ``-p``) を使用します。
bin/cake migrations migrate -p MyAwesomePlugin

rollback : マイグレーションを戻す¶

ロールバックコマンドは、このプラグインを実行する前の状態に戻すために使われます。 これは migrate コマンドの逆向きの動作をします。 :

# あなたは ``rollback`` コマンドを使って以前のマイグレーション状態に戻すことができます。
bin/cake migrations rollback

# また、特定のバージョンに戻すために、マイグレーションバージョン番号を引き渡すこともできます。
bin/cake migrations rollback -t 20150103081132

migrate コマンドのように --source 、 --connection そして --plugin オプションが使用できます。

status : マイグレーションのステータス¶

Status コマンドは、現在の状況とすべてのマイグレーションのリストを出力します。 あなたはマイグレーションが実行されたかを判断するために、このコマンドを使用することができます。 :

bin/cake migrations status

--format (省略形は -f) オプションを使用することで JSON 形式の文字列として結果を出力できます。 :

bin/cake migrations status --format json

migrate コマンドのように --source 、 --connection そして --plugin オプションが使用できます。

mark_migrated : マイグレーション済みとしてマーキングする¶

時には、実際にはマイグレーションを実行せずにマークだけすることが便利な事もあります。 これを実行するためには、 mark_migrated コマンドを使用します。 コマンドは、他のコマンドとしてシームレスに動作します。

このコマンドを使用して、すべてのマイグレーションをマイグレーション済みとして マークすることができます。 :

bin/cake migrations mark_migrated

また、 --target オプションを使用して、指定したバージョンに対して、 すべてマイグレーション済みとしてマークすることができます。 :

bin/cake migrations mark_migrated --target=20151016204000

もし、指定したマイグレーションを処理中にマーク済みにしたくない場合、 --exclude フラグをつけて使用することができます。 :

bin/cake migrations mark_migrated --target=20151016204000 --exclude

最後に、指定したマイグレーションだけをマイグレーション済みとしてマークしたい場合、 --only フラグを使用できます。 :

bin/cake migrations mark_migrated --target=20151016204000 --only

migrate コマンドのように --source 、 --connection そして --plugin オプションが使用できます。

このコマンドは、引数としてマイグレーションバージョン番号を想定しています。 :

bin/cake migrations mark_migrated 20150420082532

もし、すべてのマイグレーションをマイグレーション済みとしてマークしたい場合、 特別な値 all を使用できます。もし使用した場合、すべての見つかったマイグレーションを マイグレーション済みとしてマークします。 :

bin/cake migrations mark_migrated all

seed : データベースの初期データ投入¶

1.5.5 より、データベースの初期データ投入のために migrations シェルが使用できます。 これは、 Phinx ライブラリーの seed 機能 を利用しています。デフォルトで、seed ファイルは、あなたのアプリケーションの config/Seeds ディレクトリーの中に置かれます。 seed ファイル作成のための Phinx の命令 を確認してください。

マイグレーションに関して、 seed ファイルのための bake インターフェースが提供されます。 :

# これは、あなたのアプリケーションの config/Seeds ディレクトリー内に ArticlesSeed.php を作成します。
# デフォルトでは、変換対象の seed は、 "tableized" バージョンの seed ファイル名です。
bin/cake bake seed Articles

# ``--table`` オプションを使用することで seed ファイルに変換するテーブル名を指定します。
bin/cake bake seed Articles --table my_articles_table

# bake するプラグインを指定できます。
bin/cake bake seed Articles --plugin PluginName

# シーダーの生成時に別の接続を指定できます。
bin/cake bake seed Articles --connection connection

1.6.4 から、 bake seed コマンドは、 --data フラグを使用することによって、 データベースからエクスポートされたデータを元に seed ファイルを作成することができます。 :

bin/cake bake seed --data Articles

デフォルトでは、テーブル内にある行を全てエクスポートします。 --limit オプションを 使用することによって、エクスポートされる行の数を制限できます。 :

# 10 行のみエクスポート
bin/cake bake seed --data --limit 10 Articles

もし、seed ファイルの中にテーブルから選択したフィールドのみを含めたい場合、 --fields オプションが使用できます。そのオプションは、 フィールドのリストをカンマ区切りの値の文字列として含めます。 :

# `id`, `title` そして `excerpt` フィールドのみをエクスポート
bin/cake bake seed --data --fields id,title,excerpt Articles

データベースの初期データ投入のために、 seed サブコマンドが使用できます。 :

# パラメーターなしの seed サブコマンドは、対象のディレクトリーのアルファベット順で、
# すべての利用可能なシーダーを実行します。
bin/cake migrations seed

# `--seed` オプションを使用して実行するための一つだけシーダーを指定できます。
bin/cake migrations seed --seed ArticlesSeed

# 別のディレクトリーでシーダーを実行できます。
bin/cake migrations seed --source AlternativeSeeds

# プラグインのシーダーを実行できます
bin/cake migrations seed --plugin PluginName

# 指定したコネクションでシーダーを実行できます
bin/cake migrations seed --connection connection

マイグレーションとは対照的にシーダーは追跡されないことに注意してください。 それは、同じシーダーは、複数回適用することができることを意味します。

use Migrations\AbstractSeed;

class DatabaseSeed extends AbstractSeed
{
    public function run(): void
    {
        $this->call('AnotherSeed');
        $this->call('YetAnotherSeed');

        // プラグインからシーダーを呼ぶためにプラグインドット記法が使えます
        $this->call('PluginName.FromPluginSeed');
    }
}

dump : 差分を bake する機能のためのダンプファイルの生成¶

dump コマンドは、 migration_diff の bake テンプレートで使用するファイルを作成します。 :

bin/cake migrations dump

各生成されたダンプファイルは、生成元の接続固有のものです（そして、そのようにサフィックスされます）。 これは、アプリケーションが、異なるデータベースベンダーの複数のデータベースを扱う場合、 bake migration_diff コマンドで正しく差分を算出することができます。

ダンプファイルは、マイグレーションファイルと同じディレクトリーに作成されます。

migrate コマンドのように --source 、 --connection そして --plugin オプションが使用できます。

主キーをカスタマイズする¶

あなたがデータベースに新しいテーブルを作成する時、 id を主キーとして 自動生成したくない場合、 table() メソッドの第２引数を使うことができます。

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products', ['id' => false, 'primary_key' => ['id']]);
        $table
              ->addColumn('id', 'uuid')
              ->addColumn('name', 'string')
              ->addColumn('description', 'text')
              ->create();
    }
}

上記の例では、 CHAR(36) の id というカラムを主キーとして作成します。

bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

さらに、Migrations 1.3 以降では 主キーに対処するための新しい方法が導入されました。 これを行うには、あなたのマイグレーションクラスは新しい Migrations\AbstractMigration クラスを継承する必要があります。 あなたは Migration クラスの autoId プロパティーに false を設定することで、 自動的な id カラムの生成をオフにすることができます。 あなたは手動で主キーカラムを作成し、テーブル宣言に追加する必要があります。

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{

    public bool $autoId = false;

    public function up()
    {
        $table = $this->table('products');
        $table
            ->addColumn('id', 'integer', [
                'autoIncrement' => true,
                'limit' => 11
            ])
            ->addPrimaryKey('id')
            ->addColumn('name', 'string')
            ->addColumn('description', 'text')
            ->create();
    }
}

主キーを扱うこれまでの方法と比較すると、この方法は、unsigned や not や limit や comment など さらに多くの主キーの定義を操作することができるようになっています。

Bake で生成されたマイグレーションファイルとスナップショットは、この新しい方法を 必要に応じて使用します。

照合順序¶

もしデータベースのデフォルトとは別の照合順序を持つテーブルを作成する必要がある場合は、 table() メソッドのオプションとして定義することができます。:

<?php
use Migrations\AbstractMigration;

class CreateCategoriesTable extends AbstractMigration
{
    public function change()
    {
        $table = $this
            ->table('categories', [
                'collation' => 'latin1_german1_ci'
            ])
            ->addColumn('title', 'string', [
                'default' => null,
                'limit' => 255,
                'null' => false,
            ])
            ->create();
    }
}

ですが、これはテーブル作成時にしかできず、既存のテーブルに対してカラムを追加する時に テーブルやデータベースと異なる照合順序を指定する方法がないことに注意してください。 ただ MySQL と SqlServer だけはこの設定キーをサポートしています。

カラム名の更新と Table オブジェクトの使用¶

カラムのリネームや移動とともに、あなたのデータベースから値を操作するために CakePHP ORM Table オブジェクトを使用している場合、 update() を呼んだ後に Table オブジェクトの新しいインスタンスを作成できることを確かめてください。 インスタンス上の Table オブジェクトに反映し保存されたスキーマをリフレッシュするために Table オブジェクトのレジストリーは、 update() が呼ばれた後にクリアされます。

マイグレーションとデプロイメント¶

もし、アプリケーションをデプロイする時にプラグインを使用する場合、 テーブルのカラムメタデータを更新するように、必ず ORM キャッシュをクリアしてください。 そうしなければ、それらの新しいカラムの操作を実行する時に、カラムが存在しないエラーになります。 CakePHP コアは、この操作を行うために使用できる スキーマキャッシュシェル を含みます。 :

// 3.6.0 より前の場合、orm_cache を使用
bin/cake schema_cache clear

このシェルについてもっと知りたい場合、クックブックの スキーマキャッシュシェル セクションをご覧ください。

テーブルのリネーム¶

プラグインは、 rename() メソッドを使用することでテーブルのリネームができます。 あなたのマイグレーションファイルの中で、以下のように記述できます。

public function up()
{
    $this->table('old_table_name')
        ->rename('new_table_name')
        ->save();
}

schema.lock ファイル生成のスキップ¶

diff 機能を動作させるために、 .lock ファイルは、migrate、rollback または スナップショットの bake の度に生成され、指定された時点でのデータベーススキーマの状態を追跡します。 例えば本番環境上にデプロイするときなど、前述のコマンドに --no-lock オプションを使用することによって、このファイルの生成をスキップすることができます。 :

bin/cake migrations migrate --no-lock

bin/cake migrations rollback --no-lock

bin/cake bake migration_snapshot MyMigration --no-lock