こんにちは、Webエンジニアの仁木です。

システム開発では必ず必要になるデータベース。
開発の際には、何回もテーブルの設計を確認することになりますが、テーブル設計やER図のドキュメントはみなさんどのように作成されているでしょうか。

エクセルなどの表計算ソフトで作成されることもあると思いますが、テーブル設計というのは開発期間中に何度も修正が入ってくるため、資料の修正も頻繁に必要になってきます。
資料を手入力で修正すると修正漏れや入力ミスなどが起こるので、自動出力できるようにしてしまいましょう。

そこで「tbls」というドキュメント生成ツールが良かったので、今回紹介したいと思います。

tblsとは

tblsは様々なデータベースのドキュメントを生成してくれるツールです。
対応しているデータベースは「PostgreSQL、MySQL、MariaDB、SQLite、Amazon DynamoDB」などなど、主要なデータベースはもちろんその他も対応しているみたいです。（ちなみにGo言語で書かれているようです。）

データベースの接続情報や、ドキュメントの出力設定を書いたコンフィグを用意してツールを実行するこことで、tblsがデータベースを解析していい感じにドキュメントを生成してくれるみたいです。
データベースから直に情報を参照してドキュメントを作成するので、簡単に最新の状態のドキュメントを作れて素敵です。

データベースのテーブル毎にマークダウン形式で⇓のような感じで出力してくれます。
マークダウンなので、GitHubでもいい感じに表示してくれます。

テーブルにあるカラムの詳細や、関係のあるテーブル同士のER図やリレーション図も一緒に出力してくれています。
図はmermaid記法で書かれているため、マークダウンでもいい感じに表示してくれていますね。（テーブルが増えるとちょっと見づらくなります‥。）

tblsの使い方

tblsはdockerイメージが配布されているので、ローカルマシンにインストールせずに利用できます。
他にもMacならHomebrew、LinuxならRPMなどで配布されているので、ローカルマシンにインストールして使いたい場合はそちらからインストールできます。

Dockerならコンフィグファイルを用意してあげたら、コマンド一発でドキュメントを出力してくれてオススメです。

注意点としては、実行マシンからデータベースに接続できるようにしておく必要があります。

コンフィグの用意

yml形式のコンフィグファイルを用意します。
最低限書く必要があるのはいけないのはデータベースの接続情報のみです。

ドキュメントの出力先

実行時のディレクトリからの相対パスで指定します。

ER図

ER図をドキュメントに追加します。出力フォーマットはmermaidの他に画像やSVGなども対応しています。

ツールの起動

以下のコマンドでツールを起動します。

出力フォーマットを変える

デフォルトの出力はマークダウンですが、コマンドオプションで指定することでUML、画像、JSON、YAML、エクセルなどのフォーマットにも対応しています。

まとめ

興味のある方は一度ドキュメント出力してみてください。私はデータベースのドキュメント生成方法を調べていてこのツールに辿り着きましたが、⇓の部分が気に入っています。

• マークダウンで出力されるので、GitHubなど各サービスやエディターでいい感じに確認できる。
• Dockerのコマンド一発でドキュメントを出力してくれる。（ソフトのインストールなど、使うまでの準備がほとんどない）
• コンフィグで設定できる内容も多く、GitHubの公式ドキュメントでも一通り使い方を書いてくれている。

コンフィグを用意しておけば他のシステム案件でも使い回しできるので、データベースの資料作成や共有にかける時間がかなり短縮できたと思います。