tblsでDBスキーマのドキュメントを生成

tbls を使って、データベースのスキーマ情報のドキュメントをおこす。

https://github.com/k1LoW/tbls

導入はパッケージ管理ツールを使ったり、いくつか方法が紹介されている。

Homebrewで導入できるため、Macな人はそちらを選択しましょう。

https://formulae.brew.sh/formula/tbls

プロジェクトのリポジトリ内に .tbls.yml ファイルを作成して、接続するDBサーバーの情報、ドキュメントの出力先のパスを記述する。

cd your-project-root

# tbls.yml という名前でもよい
vi .tbls.yml

ファイルの内容は下記のような感じです。

#
# @see https://github.com/k1LoW/tbls
#

# Data Source Name
## @see https://github.com/k1LoW/tbls#dsn
dsn: postgres://user:pass@localhost:5432/dbname
# SSLモードを無効にして接続する場合
# dsn: postgres://user:pass@localhost:5432/dbname?sslmode=disable

# tbls doc コマンド で生成するファイル(markdownやER図のSVG)を出力するパス
docPath: docs/database/

Data Sourceには、PostgreSQL以外にMariaDB、BigQuery、DynamoDBなどをサポートしている。接続時に必要に応じてcredentialを記述することをお忘れなく。

早速、ドキュメントを生成してみよう。

# .tbls.yml ファイルを配置したパスにカレントディレクトリを移して、以下のコマンドを実行
tbls doc

指定したドキュメントファイルの出力先のパスにファイルができているでしょうか。

できない場合は、 .tbls.yml を見直してみたり、出力されたエラーメッセージを元にissueを探してみましょう。

PostgreSQLのpublicスキーマのみをドキュメント対象としたい場合は .tbls.yml ファイルに次の内容を追記。

include:
  - public.*

例えば、Supabaseでは予め auth や storage といったスキーマが用意されています。それらのスキーマは直接アプリケーション中から参照するようなケースは少ないかと思います。予め用意されたスキーマは、Supabaseの機能中で隠蔽化されているようなものなので、ドキュメント化しておく必要性は低いのかなと思います。(もちろん、ドキュメント化しておきたいという場合は除きます)

マイグレーションツールの Prisma を用いていると、_prisma_migrations テーブルが作成されます。マイグレーションの履歴・状況が記録されるテーブルです。

アプリケーションで、このテーブルは利用しないためドキュメントから対象外にしてもよいかと思います。

exclude:
  - public._prisma_migrations

Sequelize を用いているケースも同様です。 マイグレーションすると SequelizeMeta というテーブルが作成されます。これもドキュメント対象から外してもよいと思います。

exclude:
  - public.SequelizeMeta