tblsというDBドキュメンテーションツールを、docker composeを使って最速で導入する方法を紹介します。
なぜtblsなのか？
tblsはDBドキュメンテーションツールで、データベースのスキーマに基づいてドキュメントを自動生成してくれます。
また、ドキュメントを生成するだけでなく、生成されたドキュメントに基づいてテーブルやカラムにコメントが付けられているかなどをCI上でチェックすることもできます。
このような特徴のおかげで運用のしやすいDBドキュメント環境を作ることができます。
実際に作ったドキュメントは以下のようなものです。
tblsの使い方
ここで紹介する実装は以下のリポジトリで公開しています。
compose.ymlを書く
tblsの最も簡単な導入方法はdocker composeを使うことです。
この方法では設定ファイルさえ作ればコマンド一つでドキュメントを生成できます。
設定はcompose.ymlに書き、書く内容はGitHubのREADMEにあるものを参考に書きます。
version: "3"
services:
db:
image: mysql:8.3
platform: linux/amd64
environment:
MYSQL_DATABASE: cms
MYSQL_USER: asunaro
MYSQL_PASSWORD: password
MYSQL_ROOT_PASSWORD: password
ports:
- "3306:3306"
volumes:
- db_volume:/var/lib/mysql:cached
- ./db/conf.d:/etc/mysql/conf.d
migrate:
build: ./db/migrations
depends_on:
- db
command: ["up"]
environment:
WAIT_HOSTS: db:3306
MIGRATIONS_DIR: /migrations
MYSQL_HOST: db
MYSQL_PORT: 3306
MYSQL_DATABASE: cms
MYSQL_USER: asunaro
MYSQL_PASSWORD: password
volumes:
- ./db/migrations/migrations:/migrations
tbls:
image: ghcr.io/k1low/tbls
working_dir: /db
volumes:
- ./db/:/db
depends_on:
- migrate
entrypoint: >
tbls doc mysql://asunaro:password@db:3306/cms
volumes:
db_volume:
driver: local
ここでは以下の3つのサービスを定義しています。
- db
- migrate
- tbls
dbはその名の通りmysqlのコンテナを作ります。
migrateはDBマイグレーションを行うためのサービスです。（これに関しては別記事で紹介する予定です）
そして3つ目のtblsがDBドキュメントを生成するサービスです。
DBドキュメントの生成にはmysqlコンテナが立ち上がっているのはもちろんのことmigrateも行われている必要がありますのでdepends_onにmigrateを設定しています。
また、volumesを設定しているのはdbドキュメントがコンテナ内に生成された際にそれをホスト側に反映させるためです。
ここではコンテナ内のdbディレクトリをローカルのdbディレクトリにマウントさせ、コンテナ内のworking_dirをdbディレクトリに設定することでdb配下に吐き出したDBドキュメントがホストのdbディレクトリにそのまま反映されます。
このような設定を行ったうえで以下のコマンドを実行すればDBドキュメントを実際に生成することができます。
docker compose up
tblsの設定ファイルを書く
tblsはドキュメントを生成する際にも様々な機能を使うことができ、代表的なものとしては以下に挙げるようなものがあります。
- viewpointsを使っていくつかのテーブルをまとめることができる
- relationsで外部キー制約を設定せずともカラムの参照関係を表現できる
- commentsを使ってスキーマに定義されていないコメントをドキュメントに記載できる
これらの機能はtbls.ymlという設定ファイル内に書くことでドキュメントに反映することができます。
tblsのちょっと残念な点
このように非常に簡単にDBドキュメント環境を作れるtblsですが、いくつか残念な点もあります。
中でも自分が困ったのは以下の2つです。
- カラム同士の参照関係を自動判定する際の自由度が少ない
- アウトプットとしてhtmlを指定できない
前者は例えばsome_table.user_id -> user.idなどの参照関係は自動判定できますが、some_table.user_id -> user.user_idのように少し異なる命名規則を採用している場合には検出できなくなります。
これに関してはrelations機能を使えばカバーできるのですが、どうしても運用に一手間かかってしまいます。
また、後者に関してはおそらくtblsがGitHub等で直接見れるドキュメントを生成することを目的としていることに起因しています。
tblsのこの方針はドキュメントのインデックスページがREADME.mdとして吐き出されることからも察せられます。
確かにエンジニアだけがDBドキュメントを見るのであればGitHub上で見れさえすれば全く問題ありません。
ただ、得てしてDBドキュメントを欲しがっているのはシステムに明るくないPdMや営業さんだったりします。
そして、これらの非エンジニアはGitHubのアカウントを持っていなかったりします。
そうするとこれらのメンバーはGitHub上で直接ドキュメントを見ることはもちろんできず、GitHub Pages上でも見ることはできません。
となるとS3等の静的ホスティングサービスを使うことになりますが、そのためにはmdファイルをhtmlファイルに変換する必要があります。
mdファイルをhtmlファイルに変換するツールとしてはMkDocs等が有名なので、もちろんやろうと思えば可能ですが一手間かかってしまうのは事実です。
まとめ
本記事ではDBドキュメントをおそらく最も簡単に生成する方法を紹介しました。
ドキュメントは運用されなければ意味がありません。
tblsは手軽に導入できるだけでなくそのような負担を軽減しつつ運用できるのでDBドキュメントを作りたい方にとってはかなりいいソリューションになり得ると思います。
