tblsでデータベースドキュメントを生成する（1.ドキュメント生成編） #MySQL

ドキュメント生成編

テーブル情報補完編

CI連携編

tblsを使うと、1コマンドでデータベースドキュメントを生成できます。

tbls とは

tblsのKey featuresには以下のように記載しています

Document a database automatically in GFM format. Output database schema in many formats.
- 1コマンドで、Markdown形式で生成されますので、そのままGitHubなどのリポジトリにコミットして閲覧することができます（ドキュメントも更新履歴が残ったほうがいいですからね）。
- 上記以外にもスキーマをPlantUMLやJSON、Excelファイルで出力する機能などもあります
Single binary = CI-Friendly.
- Goで書かれているため、バイナリポン置きで利用できます。つまり、CIに組み込み安いということです。
Support many databases.
- v1.24.1 時点ででサポートしているデータベースは以下の通りです
  - PostgreSQL
  - MySQL
  - SQLite
  - BigQuery
  - Cloud Spanner
  - Amazon Redshift
  - Microsoft SQL Server
  - Amazon DynamoDB
Work as linter for database.
- ドキュメント生成だけでなくLinterとしても動きます

インストール

tblsはGo製のCLIツールなのでgo getでインストールできます。

$ go get -u github.com/k1LoW/tbls

Macの場合はHomebrewでインストールすることも可能です。

$ brew install k1LoW/tap/tbls

Docker imageも用意されています

$ docker pull k1low/tbls:latest

オプション: Graphviz のインストール ER図もtbls単体で生成可能

tbls v1.27.0からER図の生成もtbls単体で生成可能になっています

データベースドキュメントの生成

以下のように .tbls.yml を作成します。

# .tbls.yml

# 接続先として、データベースの種類(`mysql`)、ユーザ名(`dbuser`)、パスワード(`dbpass`)、ホスト名(`localhost`)、ポート(`3306`)、データベース名(`dbname`)を以下のように記載します
dsn: mysql://dbuser:dbpass@localhost:3306/dbname

# ドキュメントのディレクトリを指定します
docPath: doc/schema

あとは tbls doc を実行します

$ tbls doc

これだけでデータベースドキュメントが生成されます。

これらをGitHubなどにコミットすれば、このような感じでコミット可能なドキュメントとしてデータベース情報を確認できます。

.tbls.ymlを使わないでドキュメント作成

.tbls.ymlを作らなくてもワンライナーでのドキュメント生成が可能です。

PostgreSQLだと以下のように.tbls.ymlの dsnとdocPathの情報を引数に渡すことで作成できます。

$ tbls doc postgres://user:pass@hostname:5432/dbname ./dbdoc

（接続できない場合は ?sslmode=disable を付与してください）

たった1コマンドでデータベースのドキュメント生成ができました。

次はドキュメントにリレーション情報やコメントを補完する方法を紹介します。