ドキュメント整備のためにtblsを導入してみた話

この記事は さくらインターネット Advent Calendar 2023 23日目の記事です。

はじめまして。さくらインターネットに2023年新卒で入社した知念です。バックエンドエンジニアとして、さくらのクラウドというIaaS系サービスの開発に関わっています。
今回はデータベースのドキュメント整備のためにtblsというツールを導入した話をします。

## きっかけ

僕が開発に関わっているプロジェクトでパフォーマンス向上のためにSQLのクエリを修正する機会が最近ありました。その時に、テーブル設計を理解するため、全体像やテーブル情報を俯瞰的に見られるドキュメントがほしいなと思い、良い感じの解決策や使い勝手の良いツールはないかなと探し始めたのがきっかけでした。

## 先輩に相談してみた

僕 「DBのER図とか可視化された何かを楽に用意したいんですよねー」

先輩 「ほうほう」

僕 「調査に少し時間かけてしまったので、今後同じように新しいメンバーが入ってきた時にもう少し楽に進められるようにしたいです
アプリケーションの構造理解を深める意味でもあると役に立ちますし(しばらく経ったら僕も忘れてそう...)
何か良さげなツールって知ってたりしますか?」

先輩 「それならtblsとかどうですかー?」


## tblsとは?
一言でまとめると、DBのドキュメントを自動生成できるOSSのツールです。ちなみに、Goで書かれています。

## 特長

- データベーススキーマをmarkdownや画像など[さまざまな形式](https://github.com/k1LoW/tbls#output-formats)で出力可能
- Goで書かれているためバイナリポン置きできる
- ↑ができるのでCIに組み込みやすい
- [対応しているデータベース](https://github.com/k1LoW/tbls#support-datasource)	も多い
    - PostgreSQL, MySQLなどはもちろんBigQueryでも使えるらしい

## 導入方法

コンテナから手動実行、Github ActionsでCI実行時に自動実行される形にしたかったので、以下の2つで試しました。
また、データベースはMySQLを使用しています。

- Docker
- Github Actions

## Dockerを使って導入する場合

[README](https://github.com/k1LoW/tbls#quick-start
)に書いてあるDockerのimageを使用します。
今回は、他に立ち上げるサービスがあることも考慮してdocker-compose.ymlに書きます。


<details><summary>doker-compose.yml</summary>

```docker-compose.yml
  tbls:
    image: ghcr.io/k1low/tbls:latest
    volumes:
      - ./tbls.yml:/tbls.yml
      - ./dbdoc:/dbdoc
    command: doc --rm-dist
    profiles:
      - tbls
    env_file:
      .env
```
</details>

## Github Actionsに導入する場合

公式の[README](https://github.com/k1LoW/tbls#quick-start
)にセットアップ方法が書いてあるので、そちらをそのまま使用します。

[setup-tbls](https://github.com/k1LoW/setup-tbls)というセットアップツールが用意されていて、そちらを呼び出せば使える形なので、Github Actionsでも手軽に導入できます


<details><summary>.github/workflows/doc.yml</summary>

```.github/workflows/doc.yml
name: Document

on:
  push:
    branches:
      - main

jobs:
  doc:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout .tbls.yml
        uses: actions/checkout@v3
      -
        uses: k1low/setup-tbls@v1
      -
        name: Run tbls for generate database document
        run: tbls doc
```

</details>

## 使えるコマンド色々

### ドキュメントを生成

以下のコマンドでドキュメントが生成されます。

```bash
$ tbls doc mysql://dbuser:dbpass@hostname:3306/dbname
```


データベースの情報等は後述するymlに書くことで省略できます。

```bash
$ tbls doc
```

#### 生成されたドキュメント

以下のように各テーブルごとにmarkdownの表とsvg画像が出力されます。(以下はサンプル)

```
dbdoc/schema.svg
dbdoc/ar_internal_metadata.svg
dbdoc/schema_migrations.svg
dbdoc/services.svg
dbdoc/users.svg
dbdoc/README.md
dbdoc/ar_internal_metadata.md
dbdoc/schema_migrations.md
dbdoc/services.md
dbdoc/users.md
dbdoc/schema.json
```
READMEには各テーブルの情報がまとめて出力されます。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/508580/f0ccbbb6-0cca-b293-bd10-154979e0fe7d.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/508580/dbe9579b-e3eb-d154-99bf-bc21d959ac56.png)


### ドキュメントを再生成したいとき

一度ドキュメントが生成された状態で`tbls doc`を入力すると以下のエラーが出るので、[ドキュメントを一度削除して再度生成するか強制的に上書きする必要](https://github.com/k1LoW/tbls#re-generating-database-documentation)があります。

```
output ER diagram files already exists
```

#### ドキュメントを強制的に上書き
```
$ tbls doc --force
```

#### ドキュメントを一度削除して再生成

```
$ tbls doc --rm-dist
```

### 差分

tblsではデータベーススキーマと生成された[ドキュメントの差分](https://github.com/k1LoW/tbls#diff-database-and--document-or-database-)を確認できます。

```
$ tbls diff
```

## 設定ファイル

tblsでは、`.tbls.yml` or `tbls.yml`というファイルにtblsの設定を書きます。

```tbls.yml
# DSN(Database Source Name)。接続先データベースの情報を書く。
dsn: mysql://dbuser:dbpass@hostname:3306/dbname

# ドキュメントの出力先パス。デフォルトは`dbdoc`
docPath: doc/schema
```
また、yml内では`${DATABASE_USERNAME}`のように書くことで環境変数を使用できます。

```yml
dsn: mysql://${DB_USER}:${DB_PASS}@${HOSTNAME}:3306/dbname
```

<details><summary>tbls.yml</summary>

```tbls.yml
dsn: mysql://${DATABASE_USERNAME}:${DATABASE_PASSWORD}@${DATABASE_HOST}:3306/app_development
```

</details>

### DBの情報を追記

tblsでは、yml内にテーブルの説明等のコメントを書くことでドキュメントに追加で情報を残すことができます。

```tbls.yml
comments:
  -
    table: users
    tableComment: Users table
    columnComments:
      name: ユーザ名
      created_at: 作成日
      updated_at: 更新日
```

## 実際に使ってみて...

今まではRailsのModels等を直接確認して調べることが多かったのですが、
- 複雑になってきている箇所もあり、少し調べ物する場合やRails書き慣れていない場合理解までに時間が必要
- それでもわからなかった場合、知っていそうな先輩エンジニアに聞きに行くケースがそれなりに多いので手間をかけてしまう

といった課題がありました。

どういった使い方が自分たちのチームでは適切なのか検討していく段階だと思いますが、ひとまず使ってみた感想としては

- 軽く全体像を確認する程度なら自動生成されたドキュメントを見るだけでも十分使える
- 追加情報は`tbls.yml`に集約されるので管理しやすい
- tbls.ymlのコメント等でドキュメントに足りない情報を補っていていけば、チームの情報共有場所になり誰かに聞きに行く頻度が減る
- Github Actionsでデータベースの構造に変更があった場合などは自動更新できるので管理も楽そう

と言った感じで、今後も使いどころを試行錯誤していけると良いなと思いました。

## まとめ

今回はtblsでデータベースのドキュメントを管理する話をしました。
tblsはCIで回すことができて補足情報もymlで管理できるため、触ってみた感触としては良さそうでした。

まだ十分に扱いきれてない部分が多いですが、今後も使い方を模索しつつ新しい知見があれば引き続きブログとして残せればと思います💪

何か質問などあれば気軽にコメントください
ここまで読んでいただきありがとうございましたー


## 参考

https://github.com/k1LoW/tbls

https://qiita.com/k1LoW/items/2010413a8547b1e6645e

https://qiita.com/k1LoW/items/92d1be1437a259827338

https://github.com/k1LoW/setup-tbls

https://k1low.hatenablog.com/entry/2023/02/16/093315