こんにちは、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を外部の開発会社と共有して並行開発してもらうときにそのままスキーマの資料として参照してもらうこともできそうです。nameやdateといったつるんつるんのカラム名に何の説明もないままだと、山ほど問い合わせが来たりしますよね。
参考: 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より
カラムのコメント機能をそこまで徹底的に使う必要はあまりなさそうですが、念のため。