tblsを使ってデータベースドキュメントのメンテナンス性を爆上げ！

こんにちは、GMOメイクショップの黒木です。

弊社は、データベースドキュメントのメンテナンス性を向上させるため、tblsというツールを導入しました。この記事では、導入した経緯と活用事例についてご紹介します。

tblsとは
tblsを導入した経緯
活用事例
まとめ

tblsとは

tblsとは、データベースのドキュメントを自動生成するツールです。

github.com

tblsは、データベースのドキュメントを簡単に生成できるのが大きなポイントです。以下のように、カラム一覧、制約一覧、インデックス一覧をはじめとしたドキュメントが、たった1コマンドで生成できます。

さらに、tblsは以下のようなER図も簡単に生成できます。

tblsを導入した経緯

弊社ではこれまで、手動でデータベースのドキュメントを作成・更新していましたが、いくつかの課題がありました。そこで、効率的でメンテナンス性の高いドキュメント管理ツールを探した結果、tblsの特徴に魅力を感じ、導入に至りました。

テーブル定義とドキュメントの乖離を防止できる

手動でドキュメントを作成・更新していた際、更新漏れが原因で、実際のテーブル定義とドキュメントの内容にズレが生じることがありました。しかし、tblsはテーブル定義から自動でドキュメントを生成するため、常に最新の情報が反映され、テーブル定義とドキュメントの乖離を防ぐことができます。

テーブル定義を変更せずに、カラムコメントの設定ができる

社内の制約により、データベース上でカラムコメントを直接設定できない箇所がありましたが、tblsを使えば、ドキュメント上でカラムコメントを自由に設定できます。テーブル定義を変更することなく、コメントを管理できる点が非常に便利でした。

以下のように、tblsの設定ファイルにカラムコメントを設定することで、簡単にカラムコメントを設定できます。

comments:
  - table: orders
    tableComment: 注文情報を格納するテーブル
    columnComments:
      order_id: 注文ID（注文ごとに一意なキー）
      product_id: 商品ID（商品ごとに一意なキー）
      user_id: 会員ID（会員ごとに一意なキー）
      quantity: 数量

テーブル定義を変更せずに、外部キーの設定ができる

同様に、社内の制約で外部キーが設定できない箇所がありました。しかし、tblsではドキュメント上で外部キーを設定できるため、テーブル定義を変更せずに外部キーの管理が可能です。

以下のように、tblsの設定ファイルにリレーションを設定することで、簡単に外部キーを設定できます。

relations:
  - table: orders
    columns:
      - product_id
    parentTable: products
    parentColumns:
      - product_id
    def: orders->products

活用事例

弊社では、ドキュメントとしての活用だけでなく、ドキュメント内のカラムコメントとDTOのフィールドコメントを同期させることで、開発支援を行っています。

これまでは、DTOのフィールド内容を把握するために、その都度ドキュメントを見に行く必要がありました。都度見に行くのは手間がかかるため、ドキュメントのカラムコメントを、DTOのフィールドコメントに自動反映させるツールを作成して、この手間を解消しました。

ツールを実行すると、ドキュメントのカラムコメントが、@schemaをプレフィックスにして、以下のようにフィールドコメントとして反映されます。

type Orders struct {
   // @schema 注文ID（注文ごとに一意なキー）
   OrderId int
   // @schema 商品ID（商品ごとに一意なキー）
   ProductId int
   // @schema 会員ID（会員ごとに一意なキー）
   UserId int
   // @schema 数量
   Quantity int
}