tblsでコメントをSQLとは別に管理する

tbls を使ってDBドキュメントを生成するときに、テーブルやカラムのコメントだけ別で管理する方法を紹介します。

動作環境

• tbls 1.8.3
• PostgreSQL 11.2
• macOS Mojave 10.14.3

背景

tbls を使ってデータベース定義のドキュメントを自動生成していますが、次の理由からSQLのCOMMENT文とは別にコメントを管理したいというニーズがありました。

• DBマイグレーションツールを使っているため、テーブル定義を変えるたびに新しいSQLファイルが追加されることになるが、COMMENT文を使う方法だと最新のコメントがあちこちに分散する
• DBマイグレーションツールがSQLファイルのチェックサムを管理¹ しており、コメントにtypoがあっただけの場合でも（元のSQLファイルではなく）別のSQLファイルを追加しなければならず煩雑になる

解決方法

tbls にはリレーションやコメントに関する追加情報を与える機能があるので、これを使えばコメントだけを別で管理することができます。

• Configration - Comments
• Configration - Relations

例えば、次のような定義のテーブルがデータベース上に存在しているとして、

CREATE TABLE book (
  id           serial PRIMARY KEY,
  title        varchar(100) NOT NULL,
  author       varchar(100) NOT NULL,
  published_on date NOT NULL
);

マイグレーションSQLとは別に、以下のようなYAMLファイルにテーブルやカラムのドキュメントコメントを記載してあげます。

db.yml

comments:
  -
    table: book
    tableComment: 書籍を管理するテーブル
    columnComments:
      title: タイトル
      author: 作者
      published_on: 出版日

あとは、tblsを実行するときに --config オプションでこのファイルを指定するだけです。

$ tbls doc --config db.yml \
    postgres://user:pass@localhost:5432/testdb?sslmode=disable ./dbdoc

生成されたドキュメントを確認すると、コメントが埋め込まれていることが分かると思います。

./dbdoc/book.md

# book

## Description

書籍を管理するテーブル

## Columns

| Name | Type | Default | Nullable | Children | Parents | Comment |
| ---- | ---- | ------- | -------- | -------- | ------- | ------- |
| id | integer | nextval('book_id_seq'::regclass) | false |  |  |  |
| title | varchar(100) |  | false |  |  | タイトル |
| author | varchar(100) |  | false |  |  | 作者 |
| published_on | date |  | false |  |  | 出版日 |
...

補足

• tbls 1.6.0 より前は、 --config オプションではなく --add オプションでしたが、今後は --config が推奨です
• 必ずしもすべてのテーブル＆カラムにコメントを付ける必要はなく、コメントを付けたいものだけを記載すればOKです

参考情報

• tbls is a CI-Friendly tool for document a database, written in Go.
• tblsでデータベースドキュメントを生成する（2.テーブル情報補完編）

---

1. ここでは、DBマイグレーションツールとして Flyway を想定しています。チェックサムの検証を無効化するオプションもありますが、意図しない修正を検出するために外したくないという事情があります。 ↩