Upgrade to Pro — share decks privately, control downloads, hide ads and more …

20210618_出張!Railsウォッチ in 銀座Rails#34

20210618_出張!Railsウォッチ in 銀座Rails#34

Masato Mori

June 18, 2021
Tweet

More Decks by Masato Mori

Other Decks in Programming

Transcript

  1. 出張!Railsウォッチ

    in 銀座Rails#34

    森 雅智 / @morimorihoge
    2021/06/18
    1

    特集:~もっとDBコメントを書こう!~



    View full-size slide

  2. 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


    View full-size slide

  3. Railsウォッチとは?

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

    3


    View full-size slide

  4. これまでの出張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 


    View full-size slide

  5. もっとDBコメントを書こう!

    5

    今日の動作確認環境

    ● Ruby 3.0.1p64

    ● Rails 6.1.3.2

    ● PostgreSQL 13.3


    View full-size slide

  6. DBの(テーブル|カラム)コメント、書いてますか?

    ● 必ず書く派

    ● 自分が作るテーブル・カラムには付ける派

    ● 気にしない派

    ● 不要(あったら消す)派

    6


    View full-size slide

  7. そもそもDBコメントって何?

    ● DBのテーブルやカラムにメタデータとして付与できる説明用のコメント文字列(SQL
    のコメントではない)

    ○ コメント機能の仕様自体はRDBMSによって異なるため、生SQLで扱う際には細かい差違はある 

    ○ MySQL、PostgreSQLはRails標準サポート。Oracleはactiverecord-oracle_enhanced-adapterを入れ
    れば対応できる。SQLite3は仕様上なさそう 

    ■ ※未対応の環境で使おうとするとNotImplementedErrorが発生する 

    7


    View full-size slide

  8. RailsでDBコメントを使う方法

    ● migration時に以下の方法で付与できる

    ○ スキーマ記述時に comment: ‘コメント’ 形式のオプションを付ける 

    ○ change_table_comment :テーブル名, ‘コメント’
    ○ change_column_comment :テーブル名, :カラム名, ‘コメント’

    8

    RDBMSごとの差違はActiveRecordさんが吸収してくれます


    View full-size slide

  9. psqlでのコメント確認方法

    ● PostgreSQLでは `\d`や `\dt`に`+`を付けることで表示される

    ● MySQLは

    ○ `SHOW TABLE STATUS LIKE #{table}`や 

    ○ `SHOW FULL COLUMNS FROM #{table}`を使えば良い
    9


    View full-size slide

  10. schema.rbでコメントを確認する

    ● Rails管理のschema.rbにも適宜コメントが反映される

    10

    ポイント

    ● schema.rbはdb:migrateしてれば自動的に最新のテーブルスキーマと同じになって
    いるはずなので、とりあえずschema.rbを見れば最新仕様が分かると思って良い


    View full-size slide

  11. DBコメントがうれしいケース:用語定義入り交じり問題(1)

    ● 仕様策定時は多くの場合主要となる言語(つまり日本語)でユビキタス言語(業務
    上名付けた用語)を定め、シナリオを整理する

    ○ 例:「注文」「価格」「税抜価格」「消費税率」など 

    ● ユビキタス言語をプログラムに落とす際、英語に変換する

    ○ 例:「purchases」「price」「price_without_tax」「tax_rate」など 

    ● システムに近いプログラマは英語名でモノを考えるが、ビジネスサイドは日本語で
    モノを考えるという齟齬が発生し、しばしば行き違いが発生する

    ○ ビジネスサイド「税抜価格が1000円以上の商品だけ抽出して」 

    ○ 先週JOINしたプログラマ「税抜価格?...お、priceかな?」 -> 😇😇😇

    11

    ※ローマ字を使ったとしても、漢字の持つ情報が落ちるので同様の事態は発
    生する(例:`shiyou`は「仕様」か「姿容」か区別できない)


    View full-size slide

  12. DBコメントがうれしいケース:用語定義入り交じり問題(2)

    ● DBコメントがあれば・・・

    12

    プログラマ用語
 ユビキタス言語

    ● Google Sheetsなどでユビキタス言語と英語版プログラマ用語の対応表を作ったり
    することもあるが、メンテされなくなったり見るのがめんどくさくなってサボられがち

    ● テーブルコメントにしておけば、常に手元のschema.rbに対応リストがある

    ○ 仕様書と往復することが減って開発に集中できるし、仕様理解ミスによるバグも減る! 


    View full-size slide

  13. いや、別にこれくらい頭の中に入ってるし

    間違えるわけないじゃん、という人へ

    13


    View full-size slide

  14. ちょっと込み入ったシステムを考えてみる

    14

    ● 確定申告書の入力情報(赤枠部)を扱
    うテーブルを考えてみます


    View full-size slide

  15. DBコメントなしschema.rb

    15


    View full-size slide

  16. DBコメントありschema.rb

    16


    View full-size slide

  17. DBコメントがうれしいケース:仕様書出して問題(1)

    ● ある日突然「別システムと接続連携を考えたいからDB定義書を出して」と言われる

    ● 連携予定先システム側の担当者はRailsとかわからんのでExcelでくれとか言われる

    ● 当然そんなものはないので、DB定義から自動生成できるツールとかを使って出し
    てみる

    ● 一応Excelにはなったものの、そのままでは使い物にならないので手打ちで編集し
    て提出するしかない😇😇😇😇😇

    17


    View full-size slide

  18. A5:SQL Mk-2で生成したExcel DB定義書

    18

    一見悪くなさそうに見えるが、各カ
    ラムが何を意味してるのかわから
    ないため、使い物にならない

    ※DBの物理名は業務で使われて
    いるユビキタス言語と違うため、
    プログラマ以外には全く読めない
    仕様書になってしまっている


    View full-size slide

  19. A5:SQL Mk-2で生成したExcel DB定義書(DBコメントあり)

    19

    論理名に業務で使われている用語
    が入り、物理名との対応が明らかに
    なっている。

    ここまで記述されていれば、アプリ
    ケーション側での制約(enum値や
    Modelレベルのvalidation制約)などを
    多少細くすれば使い物になる


    View full-size slide

  20. 補足(1) プログラムからDBコメントへのアクセス

    ● Railsソースコードから(テーブル|カラム)コメントを参照するには?

    20

    ※手元で確認した限りでは裏でDB問い合わせせずに返ってきたので、DBコメント参照
    がパフォーマンスボトルネックになることはなさそう


    View full-size slide

  21. 補足(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/ 


    View full-size slide

  22. まとめ

    ● DBコメントを使うとアプリケーションの名前とユビキタス言語の業務用語を近い場所
    で管理できるよ!

    ● 業務用語を正確に間違えずにコミュニケーションできると、それだけで開発の精度
    が上がるし手戻り率も下がるよ!

    ○ 特に新しく人が入れ替わった時の凡ミス率 が下げられるよ!

    ● DB定義書を自動生成するときなんかにも使えて便利だよ!

    ● 付けられない理由がなければDBコメントは付けていこうよ!

    ○ ただし用語定義の変更などがあった場合は必ず追随させる こと

    22


    View full-size slide

  23. 次回以降もブラッシュアップしていきます

    感想・リクエストなどあればTwitter

    #ginzarails

    @morimorihoge

    @hachi8833

    までお声かけください

    23


    View full-size slide