[Rails 5] マイグレーション時にデータベースのカラムにコメントを追加する

こんにちは、hachi8833です。BigBinaryシリーズで引き続きRails 5の機能を紹介いたします。データベースのカラム定義の説明をコメントで書けるこの機能は、一見地味ながら役に立ちそうです。

元記事

確認に使った環境

  • Rails 5バージョン: 5.0.1(5-0-stable
  • Rubyバージョン: 2.4.0p0
  • PostgreSQL 9.6.1

Rails 5ではマイグレーション時にコメントをカラムに追加できるようになった

Rails 4以前は、データベースのカラムにコメントを追加するのに以下のようなgemが必要でした。

pinnymz/migration_comments
PostgreSQL、MySQL、SQLiteが対象
ActiveRecord 5.0ではRuby 2.2以上が必要
ActiveRecord 4.2ではmigration_comments v0.3.2とRuby 2.1以上が必要
albertosaurus/pg_comment
PostgreSQL専用
ActiveRecord 3.0, 3.1, 3.2とRuby 1.8.7/1.9.2/1.9.3またはJRuby 1.6+が必要

Rails 5ではこの機能が標準で装備されました(#22911)。

  • 追加したコメントはデータベース側に保存されます。
  • 現時点の5.0.1ではPostgreSQLとMySQLのみが対象です↓。

Database comments. Annotate database objects (tables, columns, indexes) with comments stored in database metadata. PostgreSQL & MySQL support.
現時点のactiverecord/CHANGELOG.mdより

コメントの追加方法

db/migrate以下にマイグレーションファイルを生成したら、以下のような書式でコメントをマイグレーションファイルに追加します。

class CreatePatients < ActiveRecord::Migration[5.0]
  def change
    create_table :patients do |t|
      t.string :name, comment: "患者のニックネーム"
      t.string :first_name, comment: "患者の下の名前"
      t.string :last_name, comment: "患者の名字"

      t.timestamps
    end
  end
end

続いて以下のようにrake db:migrateを実行すれば完了です。VERSIONにはマイグレーションファイル名のバージョンを指定します。

./bin/rake db:migrate:up VERSION=20170223063422

db/schema.rbにも以下のようにコメントが反映されます。

登録したコメントはPGAdmin(PostgreSQL用)やMySQL WorkBench(MySQL用)などのGUIツールで確認できます。以下はPGAdmin4(4.1.1)で表示しました。

コメントは通常のテーブルではなく、RDBMSの奥まった部分(metadata)に登録されます。上記のGUIツールであれば簡単に見られますが、クエリで取り出そうとするとかなり面倒になります。

カラムのコメント機能のうまい使い方

カラムのコメント機能は定義を記録するという意味が大きいと思うので、頻繁に更新したりクエリで取り出したりするのはよい使い方ではなさそうですね。db/schema.rbで全コメントをいつでも一覧できるのが一番ありがたいと思います。

従来であればカラム定義をアプリのREADMEやモデルのコメントなどに書いていたと思いますが、Rails 5ではマイグレーション時にコメントで定義を書いてdb/schema.dbで参照するというのがよさそうです。Railsアプリのモデルやリレーションが成長して複雑になったときこそ、カラムの記述があちこちに散らばらずにきれいにまとまるのは大きなメリットだと思います。

db/schema.rbのテーブルごとにcomment:のインデントまでわざわざ揃えてくれているのが地味にうれしいですね。こうやって使ってくれという意図がビシビシ伝わってきます。

コメントがRDBMSのスキーマにも登録されるので、たとえばRDBMSを外部の開発会社と共有して並行開発してもらうときにそのままスキーマの資料として参照してもらうこともできそうです。namedateといったつるんつるんのカラム名に何の説明もないままだと、山ほど問い合わせが来たりしますよね。

参考: Rails 5のカラムコメント機能はまだフル装備ではない

上述のmigration_comments gemのREADMEの冒頭には以下の記述があります。大意を以下に記載します。

重要な更新情報
ActiveRecord 5.0ではコメント機能が最初からサポートされるようになりましたが、このmigration_comments gemで提供される機能の一部についてはActiveRecordのコメント機能での実装が完全ではないものがあります。これについてはActiveRecord 5.1で実装されると見込まれます。migration_comments gemが動作する(または必要になる)のはActiveRecord 5.0が最後のバージョンになることでしょう。
今後もmigration_comments gemではActiveRecord 5.0をサポート対象とする予定ですが、両者の機能には重複する部分も多いので、いずれはmigration_comments gemは不要になることでしょう。

ActiveRecord 4.2より前のバージョン、またはRuby 2.1より前のバージョンをご利用の場合は、migration_comments v0.3.2をお使いいただくようお願いします。
pinnymz/migration_comments READMEより

カラムのコメント機能をそこまで徹底的に使う必要はあまりなさそうですが、念のため。

Ruby on RailsによるWEBシステム開発、Android/iPhoneアプリ開発、電子書籍配信のことならお任せください この記事を書いた人と働こう! Ruby on Rails の開発なら実績豊富なBPS

この記事の著者

hachi8833

Twitter: @hachi8833、GitHub: @hachi8833 コボラー、ITコンサル、ローカライズ業界、Rails開発を経てTechRachoの編集・記事作成を担当。 これまでにRuby on Rails チュートリアル第2版の半分ほど、Railsガイドの初期翻訳ではほぼすべてを翻訳。その後も折に触れてそれぞれ一部を翻訳。 かと思うと、正規表現の粋を尽くした日本語エラーチェックサービス enno.jpを運営。 実は最近Go言語が好き。 仕事に関係ないすっとこブログ「あけてくれ」は2000年頃から多少の中断をはさんで継続、現在はnote.muに移転。

hachi8833の書いた記事

週刊Railsウォッチ

インフラ

BigBinary記事より

ActiveSupport探訪シリーズ