この記事は さくらインターネット Advent Calendar 2023 23日目の記事です。
はじめまして。さくらインターネットに2023年新卒で入社した知念です。バックエンドエンジニアとして、さくらのクラウドというIaaS系サービスの開発に関わっています。
今回はデータベースのドキュメント整備のためにtblsというツールを導入した話をします。
きっかけ
僕が開発に関わっているプロジェクトでパフォーマンス向上のためにSQLのクエリを修正する機会が最近ありました。その時に、テーブル設計を理解するため、全体像やテーブル情報を俯瞰的に見られるドキュメントがほしいなと思い、良い感じの解決策や使い勝手の良いツールはないかなと探し始めたのがきっかけでした。
先輩に相談してみた
僕 「DBのER図とか可視化された何かを楽に用意したいんですよねー」
先輩 「ほうほう」
僕 「調査に少し時間かけてしまったので、今後同じように新しいメンバーが入ってきた時にもう少し楽に進められるようにしたいです
アプリケーションの構造理解を深める意味でもあると役に立ちますし(しばらく経ったら僕も忘れてそう...)
何か良さげなツールって知ってたりしますか?」
先輩 「それならtblsとかどうですかー?」
tblsとは?
一言でまとめると、DBのドキュメントを自動生成できるOSSのツールです。ちなみに、Goで書かれています。
特長
- データベーススキーマをmarkdownや画像などさまざまな形式で出力可能
- Goで書かれているためバイナリポン置きできる
- ↑ができるのでCIに組み込みやすい
-
対応しているデータベース も多い
- PostgreSQL, MySQLなどはもちろんBigQueryでも使えるらしい
導入方法
コンテナから手動実行、Github ActionsでCI実行時に自動実行される形にしたかったので、以下の2つで試しました。
また、データベースはMySQLを使用しています。
- Docker
- Github Actions
Dockerを使って導入する場合
READMEに書いてあるDockerのimageを使用します。
今回は、他に立ち上げるサービスがあることも考慮してdocker-compose.ymlに書きます。
doker-compose.yml
tbls:
image: ghcr.io/k1low/tbls:latest
volumes:
- ./tbls.yml:/tbls.yml
- ./dbdoc:/dbdoc
command: doc --rm-dist
profiles:
- tbls
env_file:
.env
Github Actionsに導入する場合
公式のREADMEにセットアップ方法が書いてあるので、そちらをそのまま使用します。
setup-tblsというセットアップツールが用意されていて、そちらを呼び出せば使える形なので、Github Actionsでも手軽に導入できます
.github/workflows/doc.yml
name: Document
on:
push:
branches:
- main
jobs:
doc:
runs-on: ubuntu-latest
steps:
-
name: Checkout .tbls.yml
uses: actions/checkout@v3
-
uses: k1low/setup-tbls@v1
-
name: Run tbls for generate database document
run: tbls doc
使えるコマンド色々
ドキュメントを生成
以下のコマンドでドキュメントが生成されます。
$ tbls doc mysql://dbuser:dbpass@hostname:3306/dbname
データベースの情報等は後述するymlに書くことで省略できます。
$ tbls doc
生成されたドキュメント
以下のように各テーブルごとにmarkdownの表とsvg画像が出力されます。(以下はサンプル)
dbdoc/schema.svg
dbdoc/ar_internal_metadata.svg
dbdoc/schema_migrations.svg
dbdoc/services.svg
dbdoc/users.svg
dbdoc/README.md
dbdoc/ar_internal_metadata.md
dbdoc/schema_migrations.md
dbdoc/services.md
dbdoc/users.md
dbdoc/schema.json
READMEには各テーブルの情報がまとめて出力されます。
ドキュメントを再生成したいとき
一度ドキュメントが生成された状態でtbls docを入力すると以下のエラーが出るので、ドキュメントを一度削除して再度生成するか強制的に上書きする必要があります。
output ER diagram files already exists
ドキュメントを強制的に上書き
$ tbls doc --force
ドキュメントを一度削除して再生成
$ tbls doc --rm-dist
差分
tblsではデータベーススキーマと生成されたドキュメントの差分を確認できます。
$ tbls diff
設定ファイル
tblsでは、.tbls.yml or tbls.ymlというファイルにtblsの設定を書きます。
# DSN(Database Source Name)。接続先データベースの情報を書く。
dsn: mysql://dbuser:dbpass@hostname:3306/dbname
# ドキュメントの出力先パス。デフォルトは`dbdoc`
docPath: doc/schema
また、yml内では${DATABASE_USERNAME}のように書くことで環境変数を使用できます。
dsn: mysql://${DB_USER}:${DB_PASS}@${HOSTNAME}:3306/dbname
tbls.yml
dsn: mysql://${DATABASE_USERNAME}:${DATABASE_PASSWORD}@${DATABASE_HOST}:3306/app_development
DBの情報を追記
tblsでは、yml内にテーブルの説明等のコメントを書くことでドキュメントに追加で情報を残すことができます。
comments:
-
table: users
tableComment: Users table
columnComments:
name: ユーザ名
created_at: 作成日
updated_at: 更新日
実際に使ってみて...
今まではRailsのModels等を直接確認して調べることが多かったのですが、
- 複雑になってきている箇所もあり、少し調べ物する場合やRails書き慣れていない場合理解までに時間が必要
- それでもわからなかった場合、知っていそうな先輩エンジニアに聞きに行くケースがそれなりに多いので手間をかけてしまう
といった課題がありました。
どういった使い方が自分たちのチームでは適切なのか検討していく段階だと思いますが、ひとまず使ってみた感想としては
- 軽く全体像を確認する程度なら自動生成されたドキュメントを見るだけでも十分使える
- 追加情報は
tbls.ymlに集約されるので管理しやすい - tbls.ymlのコメント等でドキュメントに足りない情報を補っていていけば、チームの情報共有場所になり誰かに聞きに行く頻度が減る
- Github Actionsでデータベースの構造に変更があった場合などは自動更新できるので管理も楽そう
と言った感じで、今後も使いどころを試行錯誤していけると良いなと思いました。
まとめ
今回はtblsでデータベースのドキュメントを管理する話をしました。
tblsはCIで回すことができて補足情報もymlで管理できるため、触ってみた感触としては良さそうでした。
まだ十分に扱いきれてない部分が多いですが、今後も使い方を模索しつつ新しい知見があれば引き続きブログとして残せればと思います💪
何か質問などあれば気軽にコメントください
ここまで読んでいただきありがとうございましたー
参考