tblsを使って既存データベースからデータベース定義書をMarkdownで出力する方法
データベースの寿命はアプリケーションよりも長い
というけれど、データベース定義書というものが無く、カラム名やコメントやソースコードから使われ方を類推して、それっぽいところに、それっぽいデータを入れるなんてことありますよね。
またリレーションを確認するためテーブル全体を俯瞰して眺めたいって時もありますよね。
そんな時に、役立つのが既存のデータベースからデータベース定義書を作成してくれるtblsです。
tblsとは
MITライセンスで公開されているOSSです。
tbls is a CI-Friendly tool for document a database, written in Go.
Go言語で作られたデータベースをドキュメント化するためのCIフレンドリーツールです。
そうCIフレンドリーツールなんです。
ここではドキュメント生成に重点を置いて説明しますが、README.mdを見ると、下記のようなことにも対応しているのが分かります。
✔ データベースとデータベース定義書の差分を表示（Markdownのみ）
✔ データベースのlintチェック
なのでCIの中に組み込み、マイグレーションと組み合わせることで、データベースに変更が加わるPull Requestが出された時に、カラムのコメント書いてない、ドキュメント更新していないといったことが検知できます。
対応データベース
なんとRedshiftやBigQueryにも対応している模様。しゅごい。
✔ MySQL
✔ PostgreSQL
✔ SQL Server
✔ SQLite
✔ BigQuery
✔ Redshift
✔ Cloud Spanner
出力フォーマット
Markdown以外にも数多くのフォーマットに対応しています。
PlantUMLも対応しているのは嬉しいですね。そしてExcelにも……！？
✔ GitHub Flavor Markdown
✔ Dot
✔ PlantUML
✔ 画像(SVG/PNG/JPG)
✔ JSON
✔ YAML
✔ Excel
✔ tbls.yml（lint設定ファイル）
インストール方法
こちらから、バイナリをダウンロードしたり、brewやdockerを使ってインストールが可能です。
brew
brew install k1LoW/tap/tblsdocker
docker pull k1low/tbls:latest
使い方
tblsにパスを通している状態なら以下のコマンドで、
tbls doc postgres://dbuser:dbpass@hostname:5432/dbnameDockerを使うなら以下のコマンドで出力できるようになります。
docker run --rm -v $PWD:/work k1low/tbls doc postgres://dbuser:dbpass@hostname:5432/dbnameようはtblsに接続先データベース情報を渡してあげるだけですね。簡単。
上記はPostgreSQLの例ですが、MySQLなら
mysql://dbuser:dbpass@hostname:3306/dbnameSQLiteなら
sqlite:///path/to/dbname.dbとなります。（myとかsqとか省略形も用意されています）
その他はREADME.mdに書いてありますのでそちらを参照してください。
やってみた
WordPressのデータベース定義を出力してみます。
こちらのリポジトリに出力結果上げておきましたので、手っ取り早く確認したい方はこちらを見てください。
Docker上にWordPress + MySQLを構築します。
まずは下記をdocker-compose.ymlとして、任意の空ディレクトリに配置してください。
そのディレクトリ上で下記コマンドを叩きます。
docker-compose up次にブラウザで、下記のURLを開きます。
WordPressの言語選択画面が表示されたら、Docker上にWordPressのインストールができていることが確認できます。
この時点ではデータベースにデータが入っていませんので、このままWordPressのインストールを完了させていきます。
使い捨て環境なので適当に進めて行ってください。
下記画面まで設定を終えたらWordPress上の作業は完了です。
そして、tblsコマンドを叩き、WordPressのデータベース定義書をMarkdownで出力してみましょう。
ここではローカルのtblsを叩くようにします。
tbls doc mysql://wordpress:wordpress@127.0.0.1:3306/wordpress接続先情報は
{database}://{username}:{password}@{hostname}:{port}/{schema}
という形式で記述します。
コマンドを叩いたディレクトリに、dbdocディレクトリが作成され、その中にMarkdownやらPNGファイルやら色々出力されているのが確認できると思います。
README.md にスキーマ内のテーブルの情報とschema.pngが表示されています。
外部キーを使っていないので、リレーションが図に表れませんが。
※外部キー設定なくてもリレーションを表現させる方法が用意されています
wp_post なんかを見ると、post_statusのデフォルト値がpublishになっているので、記事はデフォルトが公開状態なんだなって分かりますよね。
まとめ
✔ tblsを使って既存データベースから定義書を出力することができる。
✔ 様々なデータベースに対応している。
✔ 様々な出力フォーマットに対応している。
✔ CIに組み込んでデータベース定義の差分を検知できる。
.tbls.ymlでlint設定できたりするので、その辺りを別の機会に見ていけたらと思っています。
😉