🧜‍♀️

RailsのER図をMermaidで柔軟に生成できるGemを作りました

2022/10/10に公開約4,800字

どうも、うんちです。名前が原因でZennアカウントを凍結されておりましたが、約2年の時を経て凍結が解除されたので記念に記事を投稿します。

Rails Mermaid ERDという、Ruby on RailsアプリからMermaidのERDを自由に起こせるGemを作りました。ただERDを生成するだけでなく、共有のしやすさを考慮して作っています。

↓直感的に触れると思うのでデモサイトから触ってみてください。
https://koedame.github.io/rails-mermaid_erd/example.html

ソースコードはGitHubで公開しています。
https://github.com/koedame/rails-mermaid_erd

使い方

使い方はインストールしたらコマンドを実行するだけです(詳しいインストール手順は記事の最後に書いています)。

$ bundle exec rails mermaid_erd

コマンドを実行すると ./mermaid_erd/index.html が生成されるのでこのファイルをお使いのブラウザで開いて使用してください。

ERDの共有方法

.
├── mermaid_erd
│   └── index.html

生成された ./mermaid_erd/index.html はシングルHTMLファイルです。このファイルを直接受け渡しすることでRuby on Rails環境がなくてもこのツールを使用できます。また、サーバーにアップロードすれば共通のURLで使用することも可能です。
CIで生成から共有までを自動化するとスマートですね。

表示している状態はURLのHashで管理しているため操作履歴はブラウザ履歴と連動しています。
つまり、ブラウザの戻る/進むを使うことで操作の前後を確認できます。
そしてこのHash付きのURLを共有すれば同じ画面を共有することが可能です。

↓こちらは実際の共有リンクです。

https://koedame.github.io/rails-mermaid_erd/example.html#eyJzZWxlY3RNb2RlbHMiOlsiVXNlckltYWdlIiwiUG9zdCIsIkF1dGhvciJdLCJpc1ByZXZpZXdSZWxhdGlvbnMiOmZhbHNlLCJpc1Nob3dLZXkiOmZhbHNlLCJpc1Nob3dDb21tZW50IjpmYWxzZSwiaXNIaWRlQ29sdW1ucyI6ZmFsc2V9

開くとこの画像と同じ状態の画面が表示されているはずです。
このように表示中のリンクを共有するだけで同じ状態を共有することが可能となります。
GitHubやSlackでのコミュニケーションの際にリンクを貼るだけで共有ができるのは体験として気持ち良いですね。

その他にも以下の共有方法を用意しています。

  • Mermaidコードをクリップボードへコピー
  • Markdownコードをクリップボードへコピー(GitHubのIssueやWikiにそのまま貼り付けて使うことが出来ます)
  • SVGもしくはPNGとして保存

こちらは実際にGitHubにMarkdown形式でコピーしたものをそのまま貼り付けたときの表示です。
Markdown形式であれば細かい調整を後から行うことができるため画像形式よりおすすめです。

Zennも対応していますね。

機能紹介

多くはありませんが現在の機能を紹介します。

リレーションのプレビュー機能

現在表示しているモデル(エンティティ)の関連を表示することができます。
対象のモデルがどのモデルに関連しているのかを調べたいときにとても役立ちます。

リレーションのコメントの/非表示

Railsで設定しているリレーションの情報を表示します。
has_many :comments を設定していれば HM:comments と表示されます。

カラムの表示/非表示

カラムを非表示にすることができます。関連図だけのシンプルな情報で良い場合はこのオプションが効果的です。

キーの表示/非表示

カラムのキーを表示することができます。
PK = PrimaryKey、 FK = ForeginKey なので、参照に使われているカラムをすぐに把握することができます。この表記はMermaidの仕様なので変更や追加はできません。

コメントの表示/非表示

カラムのコメント表示にも対応しています。カラム名からは把握できない情報を拾うことが可能です。
SQLiteなどのコメントに対応していないDBや、カラムコメントを設定していない場合はあまり使うことが無いかもしれません。

Mermaidコードの確認

実際に生成されているMermaidのコードをリアルタイムで確認することが可能です。

インストール手順

  1. Gemfile に追加
Gemfile
group :development do
  gem 'rails-mermaid_erd' # <= 追加
end
  1. bundle install を実行してインストール
$ bundle install
  1. 必要に応じて .gitignore に追記してGit管理対象外にする
.gitignore
mermaid_erd # <= 追記

設定

./config/mermaid_erd.yml を設置することで設定を変更できます。
設定例は こちら を参照してください。

設定項目は次のとおりです。

キー 説明 初期値
result_path 生成されるファイルのパス。 mermaid_erd/index.html

作ってみた感想

今回Railsのモデル情報を参照したものにしたけど、DBのSchemaを直接参照する方式にしておけばフレームワークや言語に依存しないからそっちのほうが価値あるよなー 🤔(伏線)

Discussion

ログインするとコメントできます