【Cakephp】全てのテーブルとカラムにコメントを付与する作業メモ

前提条件

cakephp3.xでmysqlを使用していること。

手順

1. mysqldumpでスキーマのDB定義のみを出力した 『バックアップA』 を作成

mysqldump -u {ユーザー} -p -h {DBサーバホスト} {DBスキーマ名} -d -n > schema-dump-A.sql

2. 現在のDBからマイグレーションファイルを作成

bin/cake bake migration_snapshot {マイグレーション名}

3. マイグレーションファイルを編集

• downメソッド の中身をごっそり消す
• テーブルコメント更新用のSQL処理追加
• createメソッド を updateメソッド に置換
• addColumnメソッド を changeColumnメソッド に置換
• カラムコメント追加
• addIndex の部分のコードはトルツメ
• idのchangeColumn処理追加（auto_incrementなどが元々の制約が消えないようにオプションの引数を注意する。コメントしない場合は不要。）

マイグレーションファイル

use Migrations\AbstractMigration;
use Cake\Datasource\ConnectionManager;// ← テーブルコメント更新用のSQL処理で必要なので追加

class {マイグレーション名} extends AbstractMigration
{
    public function up()
    {
      // 例） user（ユーザー）テーブルの場合
      
      // ↓ テーブルコメント更新用のSQL処理追加
      $connection = ConnectionManager::get('default');
      $connection->execute('ALTER TABLE user COMMENT :table_comment', [
          'table_comment' => 'ユーザー'
      ]);
      
      $this->table('user')
          // ↓ idのchangeColumn処理追加
          ->changeColumn('id', 'integer', ['comment' => 'ID','identity' => true]) 
          // ↓ addColumnメソッド を changeColumnメソッド に置換
          ->changeColumn('name', 'string', [
              'default' => null,
              'limit' => 255,
              'null' => true,
              'comment' => '名前' // ← カラムコメント追加
          ])
          // × addIndex の部分のコードはトルツメ
          ->update(); // ← createメソッド を updateメソッド に置換

    }

    public function down()
    {
      // 使わないので空にする
    }
}

4. マイグレーション実行

bin/cake migrations migrate

5. 再びmysqldumpでスキーマのDB定義のみを出力した 『バックアップB』 を作成

mysqldump -u {ユーザー} -p -h {DBサーバホスト} {DBスキーマ名} -d -n > schema-dump-B.sql

6. 『バックアップA』 と 『バックアップB』をテキスト差分比較しコメントだけ追加できているかチェック

コメントだけ追加できていれば成功。
もしそれ以外の箇所が違うものが書き換わっていた場合はシステムに影響が出るかもしれないので影響確認が必要。
なるべくバックアップAと一致するようにマイグレーションファイルを修正する。

トラブルシューティングTIPS

問題の箇所だけテーブルコメントみたいにSQLを直接実行する方式に置き換えれば大概解決できますが、マイグレーションのソースコードを直して解決できたものをまとめてます。

ON UPDATE CURRENT_TIMESTAMP が取れる場合

  `modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
　　↓ マイグレーション後コメント付与後
  `modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '変更日時',

対応

MYSQL default value: CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
このissueによるとchangeColumnに第３引数の配列にupdateを追加すれば良いみたい。
手順どおりのままだと自動追加されないみたいなのでマイグレーションを修正。

->changeColumn('modified', 'timestamp', [
    'default' => 'CURRENT_TIMESTAMP',
    'limit' => null,
    'null' => false,
    'update' => 'CURRENT_TIMESTAMP', // ← 追加
    'comment' => '変更日時'
])