データベースドキュメント生成コマンド tbls 更新情報（Mermaid対応 / schema.json / tbls outの強化）

Go

久しぶりのtblsの新機能紹介エントリです。

ドキュメントのER図出力にMermaidを指定できるようになりました

ER図の出力フォーマットにMermaidを指定できるようになりました。次のように er.format: セクションか --er-format オプションに mermaid を指定することで変更できます。

er:
  format: mermaid

開発裏話

GitHubがMermaid対応したことで「tblsもMermaid対応してほしい」という要望や提案は以前より多く受け取っていました。 しかし、個人的にあまりメリットを見出せずそのままPull Request待ちとなっていたのですが、今回エイッと作ってみました。

Mermaid対応をするにあたって1つとても面倒な仕様がありました。それはMermaidはER図の多重度（カーディナリティ）の指定が必須となっていることでした。

もともとtblsが持つスキーマ情報にはカーディナリティがなかったのと、カーディナリティはスキーマの情報から一意に決まるものではないので、今回のMermaid対応に向けて次の機能を追加しました。

  • リレーション情報をオーバーライドする機能（修正できる機能）
    • 自動判定されたカーディナリティを修正するため
  • スキーマ情報にカーディナリティを新たに新設
    • そもそもカーディナリティの概念がスキーマ情報になかったため
  • カーディナリティの自動判定
    • 現状と同等のステップでER図を生成するため「Mermaidの場合はカーディナリティを手入力」という方向は取れないため

Mermaid対応よりむしろこちらのほうが大変だったのはいうまでもありません。

ドキュメントの出力と同時に schema.json を出力するようになりました

ドキュメントの出力と同時に、スキーマ情報を集約した schema.json を出力するようにしました（ tbls out -t json で出力されるものと同等のものです）。出力先はドキュメントの出力ディレクトリになります。

目的としてはスキーマ情報の構造化データの保持です。

tbls doc で出力されるMarkdown形式のドキュメントはあくまでドキュメントで、構造化データとは言いにくいものです。都度データベースに接続してスキーマ情報を解析しなくても良いように一度取得したスキーマ情報を構造化データとして保持するようにしました。

開発裏話

実は、schema.jsonのファイル名を何にするかと、その出力先をどこにするかを本当に悩みました。

Issueでいろいろご意見を下さった皆様、本当にありがとうございました。

tbls out を強化しました

tbls out コマンドを強化しました。

github:// スキームに対応（ tbls out だけでなく tbls doc tbls diff でも使用可能）

schema.jsonをGitHubリポジトリから直接取得してデータソースとして使用可能です。

出力するテーブルを制御する --include --exclude --table オプションを整理。さらに --label オプションを追加

tbls out で出力するテーブルを制御するオプションを整理しました。またテーブルに付与しているラベルでも出力テーブルをフィルタリングできるようになりました。

開発裏話

tblsは基本データベースドキュメントを生成する tbls doc コマンドがフィーチャーされるので tbls out はあまり目立たないですが、個人的には今回の新機能の目玉はこちらのほうです。

schema.jsonをデフォルト出力にしたことで、将来的にはデータソースドキュメントをtblsで管理しているリポジトリには schema.json もコミットされるようになるはずです。

そうすると次のようなことが簡単にできるようになります。

$ tbls out github://k1LoW/tbls/sample/mysql/schema.json -t mermaid --table users --table posts
erDiagram

"posts" }o--|| "users" : "FOREIGN KEY (user_id) REFERENCES users (id)"

"posts" {
  bigint id PK
  int user_id FK
  varchar_255_ title
  text body
  enum__public___private___draft__ post_type
  datetime created
  datetime updated
}
"users" {
  int id PK
  varchar_50_ username
  varchar_50_ password
  varchar_355_ email
  timestamp created
  timestamp updated
}

tblsで管理されている最新のスキーマ情報をデータベース接続なしにいつでも取得できるようになります。

また、 tbls out コマンドで対応しているフォーマットにはMermaidだけではなくPlantUMLやJSON、SVG、PNGなどもあります。

私はこれを「"スキーマ情報の取得"から"スキーマ情報の活用"への道が開かられた」と捉えています。

テーブルに付与するラベルを活用することで、ラベルで意味のあるグルーピングされたテーブルのER図だけ出力するということもできます。 ここらへんのグルーピングはndiagでも実装したビューポイントの考え方につながってくると思っています*1。

というわけで、

そうです。仕込み、実はまだ続いています。

*1:https://speakerdeck.com/k1low/phperkaigi-2021?slide=49 とかをご覧ください