出張！Railsウォッチ
 in 銀座Rails#34
 森 雅智 / @morimorihoge 2021/06/18 1
 特集：～もっとDBコメントを書こう！～
 
 
 

About Me
 ● 森 雅智： @morimorihoge
 ● BPS株式会社でRailsの受託開発チームをやってたり、週1大学非常勤で Web開発を教えてたりします
 ● Ruby/Rails歴は11年くらい。Web開発は17年くらい
 ● 銀座Ralis #10でActiveRecordでVIEWを使おうという話をしました
 ● 銀座Rails #27でアプリケーションコンフィグの話をしました
 About BPS & TechRacho
 ● Web受託開発や電子書籍製品開発をやっている会社です
 ● TechRachoという自社技術Blogを運営しています
 ○ 5年ほど前から平日毎日更新してます
 ○ https://techracho.bpsinc.jp/ ● お仕事相談、転職相談、TechRachoへのご意見など気軽にどうぞ
 ○ https://www.bpsinc.jp/ 2
 

Railsウォッチとは？
 技術ブログTechRachoで毎週連載しているRails / Ruby界隈を中 心とした雑多な情報を提供する技術雑談マガジン
 3
 

これまでの出張Railsウォッチのピックアップテーマ
 ● 銀座Rails#12: 複数DB対応
 ● 銀座Rails#13: ActionText、Trix
 ● 銀座Rails#14: ActionMailbox
 ● 銀座Rails#15: production、development、staging環境について
 ● 銀座Rails#16: 機能開発の設計レビューについて
 ● 銀座Rails#17: リソース管理スコープについて
 ● 銀座Rails#19: 開発チームの冗長化について
 ● 銀座Rails#20: Excelと仲良くしよう
 ● 銀座Rails#21: 標準仕様を読むためのABNF
 ● 銀座Rails#22: CLIプログラムにOptionParserを使う
 ● 銀座Rails#23: ActiveRecordのSELECTベンチマーク
 ● 銀座Rails#24: 令和Devise事情
 ● 銀座Rails#28: 2020年の銀座Railsを振り返る
 ● 銀座Rails#29: Serverless Railsを試す
 ● 銀座Rails#30: Railsインフラ環境Overview
 ● 銀座Rails#31: Railsプロジェクトあるある
 ● 銀座Rails#32: MimeMagic騒動を振り返る
 ● 銀座Rails#33: Rails 7.0で入る予定の新機能（暫定版）
 4
 各回資料に興味がある方はこちらからどうぞ：https://speakerdeck.com/morimorihoge 
 

もっとDBコメントを書こう！
 5
 今日の動作確認環境
 ● Ruby 3.0.1p64
 ● Rails 6.1.3.2
 ● PostgreSQL 13.3
 

DBの(テーブル|カラム)コメント、書いてますか？
 ● 必ず書く派
 ● 自分が作るテーブル・カラムには付ける派
 ● 気にしない派
 ● 不要（あったら消す）派
 6
 

そもそもDBコメントって何？
 ● DBのテーブルやカラムにメタデータとして付与できる説明用のコメント文字列（SQL のコメントではない）
 ○ コメント機能の仕様自体はRDBMSによって異なるため、生SQLで扱う際には細かい差違はある 
 ○ MySQL、PostgreSQLはRails標準サポート。Oracleはactiverecord-oracle_enhanced-adapterを入れ れば対応できる。SQLite3は仕様上なさそう 
 ■ ※未対応の環境で使おうとするとNotImplementedErrorが発生する 
 7
 

RailsでDBコメントを使う方法
 ● migration時に以下の方法で付与できる
 ○ スキーマ記述時に comment: ‘コメント’ 形式のオプションを付ける 
 ○ change_table_comment :テーブル名, ‘コメント’ ○ change_column_comment :テーブル名, :カラム名, ‘コメント’
 8
 RDBMSごとの差違はActiveRecordさんが吸収してくれます
 

psqlでのコメント確認方法
 ● PostgreSQLでは `\d`や `\dt`に`+`を付けることで表示される
 ● MySQLは
 ○ `SHOW TABLE STATUS LIKE #{table}`や 
 ○ `SHOW FULL COLUMNS FROM #{table}`を使えば良い 9
 

schema.rbでコメントを確認する
 ● Rails管理のschema.rbにも適宜コメントが反映される
 10
 ポイント
 ● schema.rbはdb:migrateしてれば自動的に最新のテーブルスキーマと同じになって いるはずなので、とりあえずschema.rbを見れば最新仕様が分かると思って良い
 

DBコメントがうれしいケース：用語定義入り交じり問題(1)
 ● 仕様策定時は多くの場合主要となる言語（つまり日本語）でユビキタス言語（業務 上名付けた用語）を定め、シナリオを整理する
 ○ 例：「注文」「価格」「税抜価格」「消費税率」など 
 ● ユビキタス言語をプログラムに落とす際、英語に変換する
 ○ 例：「purchases」「price」「price_without_tax」「tax_rate」など 
 ● システムに近いプログラマは英語名でモノを考えるが、ビジネスサイドは日本語で モノを考えるという齟齬が発生し、しばしば行き違いが発生する
 ○ ビジネスサイド「税抜価格が1000円以上の商品だけ抽出して」 
 ○ 先週JOINしたプログラマ「税抜価格？...お、priceかな？」 -> 😇😇😇
 11
 ※ローマ字を使ったとしても、漢字の持つ情報が落ちるので同様の事態は発 生する（例：`shiyou`は「仕様」か「姿容」か区別できない）
 

DBコメントがうれしいケース：用語定義入り交じり問題(2)
 ● DBコメントがあれば・・・
 12
 プログラマ用語
 ユビキタス言語
 ● Google Sheetsなどでユビキタス言語と英語版プログラマ用語の対応表を作ったり することもあるが、メンテされなくなったり見るのがめんどくさくなってサボられがち
 ● テーブルコメントにしておけば、常に手元のschema.rbに対応リストがある
 ○ 仕様書と往復することが減って開発に集中できるし、仕様理解ミスによるバグも減る！ 
 

いや、別にこれくらい頭の中に入ってるし
 間違えるわけないじゃん、という人へ
 13
 

ちょっと込み入ったシステムを考えてみる
 14
 ● 確定申告書の入力情報（赤枠部）を扱 うテーブルを考えてみます
 

DBコメントなしschema.rb
 15
 

DBコメントありschema.rb
 16
 

DBコメントがうれしいケース：仕様書出して問題(1)
 ● ある日突然「別システムと接続連携を考えたいからDB定義書を出して」と言われる
 ● 連携予定先システム側の担当者はRailsとかわからんのでExcelでくれとか言われる
 ● 当然そんなものはないので、DB定義から自動生成できるツールとかを使って出し てみる
 ● 一応Excelにはなったものの、そのままでは使い物にならないので手打ちで編集し て提出するしかない😇😇😇😇😇
 17
 

A5:SQL Mk-2で生成したExcel DB定義書
 18
 一見悪くなさそうに見えるが、各カ ラムが何を意味してるのかわから ないため、使い物にならない
 ※DBの物理名は業務で使われて いるユビキタス言語と違うため、 プログラマ以外には全く読めない 仕様書になってしまっている
 

A5:SQL Mk-2で生成したExcel DB定義書(DBコメントあり)
 19
 論理名に業務で使われている用語 が入り、物理名との対応が明らかに なっている。
 ここまで記述されていれば、アプリ ケーション側での制約（enum値や Modelレベルのvalidation制約）などを 多少細くすれば使い物になる
 

補足(1) プログラムからDBコメントへのアクセス
 ● Railsソースコードから(テーブル|カラム)コメントを参照するには？
 20
 ※手元で確認した限りでは裏でDB問い合わせせずに返ってきたので、DBコメント参照 がパフォーマンスボトルネックになることはなさそう
 

補足(2) A5:SQL Mk-2
 知る人ぞ知る神ツール(Windows only)
 今ではMySQL WorkbenchやIntelliJ DataGripその他多くのリッチなGUIツールが出ている ので、DBアクセスツールとしての存在感は若干弱まった。
 しかし、日本人SIerが見慣れた感じのExcel定義書をそこそこいい感じに自動生成してく れる機能は、日本国内でソフトウェアエンジニアをやるのであればあるのとないのでド キュメント作成工数が段違いになる
 ※大手SIerでもA5:SQL Mk-2で自動生成した仕様書でOKもらったことが多々あります
 21
 https://a5m2.mmatsubara.com/ 
 

まとめ
 ● DBコメントを使うとアプリケーションの名前とユビキタス言語の業務用語を近い場所 で管理できるよ！
 ● 業務用語を正確に間違えずにコミュニケーションできると、それだけで開発の精度 が上がるし手戻り率も下がるよ！
 ○ 特に新しく人が入れ替わった時の凡ミス率 が下げられるよ！
 ● DB定義書を自動生成するときなんかにも使えて便利だよ！
 ● 付けられない理由がなければDBコメントは付けていこうよ！
 ○ ただし用語定義の変更などがあった場合は必ず追随させる こと
 22
 

次回以降もブラッシュアップしていきます
 感想・リクエストなどあればTwitter
 #ginzarails
 @morimorihoge
 @hachi8833
 までお声かけください
 23