Safie Engineers' Blog!

Safieのエンジニアが書くブログです

tblsのViewPoint機能を用いたGithub Actions上でのDBドキュメントの自動生成

サーバー・インフラ

この記事はSafie Engineers' Blog! Advent Calendar 2日目の記事です。

セーフィー株式会社でテックリードをやっております鈴木敦志です。

セーフィーはクラウドカメラのSaaSを提供しており、現在22万台程度のデバイスに対してカメラ映像をクラウドから視聴する機能を提供しています。 それに加えエンタープライズ向けの権限管理機能や社内向けの販売管理ツールなど複数のサービスを運営しており、各サービスでMySQLのDBを共有しているためDBのテーブル数が肥大化し構造がわかりにくくなり、新機能開発の妨げとなっていました。

本稿ではデータベースのドキュメンテーションツールである tbls を導入し、DBスキーマ管理ツール skeema、ドキュメント生成ツール mkdocs、Github Actionsなどと組み合わせてスキーマ管理からドキュメント生成までをやっていきます。

現在の問題点

セーフィーでは主にDBにAurora MySQLを利用しており、現在のテーブルはシャーディング用途のものを除くと452、すべて含めると5,718個あります。

各テーブルにはコメントや外部キー制約がなく、テーブルの用途を把握するにはプログラムコード内のSQLをすべて調べる必要がありました。

この問題の解決策として別途DBとコードの分割を行っており、並行してDBのドキュメント記述の仕組みの整備を行っていきます。

ドキュメント記述方法の検討 - tbls

ドキュメントの記述方法は以下の方針で検討しました。

  • テーブル定義からドキュメントを生成する
  • 上記に加え別途テーブル/カラムに対するコメントや外部キー制約を記述できる
  • テーブル定義 (今回はGithubで管理されたSQLファイル) と近い場所でドキュメントを管理できる
  • ドキュメントをCIで自動生成する

これらの要件を満たすツールとして SkeemaSpy などを検討し、CIとの親和性やyamlによる書きやすいDBメタデータ記述などを決め手に tbls を選択しました。tblsはMarkdownでドキュメントを出力するためHTMLページに変換する必要がありましたが、それには mkdocs を利用することにしました。

下図が出力例です。(サンプルのデータベースを使用しています)

tbls + mkdocs出力例

ER図には外部キー制約またはtbls設定ファイル (.tbls.yml) に記載されたリレーションが表示されます。

tbls + mkdocs出力例 (ER図)

ドキュメント生成手順

skeema によるDBスキーマの適用

セーフィーではDBスキーマを CREATE TABLE 文の記載されたSQLファイルの形式で記述し、skeema (https://www.skeema.io/) で管理しています。

ドキュメント生成のワークフローではローカルまたはGithub Actions上で起動したMySQLサーバーに対してスキーマを適用します。

tbls によるドキュメント生成

先述した tbls (https://github.com/k1LoW/tbls) ではMySQLデータベースおよび設定ファイル (.tbls.yml) をもとにMarkdownドキュメントおよび図表を出力します。

DBドキュメントを記述する際には簡単な内容であればMySQLのテーブル/カラムコメントを追記、Markdownで記述が必要なような複雑な内容であれば設定ファイルに説明を記述しています。

mkdocsによるHTML生成

mkdocs (https://www.mkdocs.org/) はpythonで実装されたMarkdownファイルからHTMLドキュメントを生成するソフトウェアです。 様々なテーマや拡張機能が用意されていて、今回は下記の構成をとりました。

現在下記 mkdocs.yml を使用しています。

site_name: "Northwindデータベース定義"
theme: "material"
plugins:
  - "search"
  - "glightbox"
extra_css:
  - "stylesheets/extra.css"
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

ドキュメント配信

生成されたHTMLドキュメントをAWS S3にアップロードし、Google WorkspaceのOpenID Connect認証をかけて配信しています。

tblsのViewPoints機能によるドキュメントの改善

tblsのテーブルコメントおよびカラムコメントだけでも一定の役にたちますが、そもそものテーブル数が多いため探しているテーブルを見つけるのが難しいという問題があります。

これに対してtblsにViewPointsという機能が実装され、ある関心ごとにテーブルをグルーピングしドキュメントを構成することができるようになりました。これにより「契約情報」「カメラ設定」などの関心ごとにテーブルの概観と関連を把握することができ、全体感を把握することが容易になりました。

ViewPointsは .tbls.yml に下記のように記述します。

viewpoints:
  - name: "商品情報"
    desc: |
      各商品は `Products` テーブルで管理され、関連するカテゴリ情報 `Categories` とサプライヤ情報 `Suppliers` の情報を持ちます。
    tables:
      - "Products"
      - "Categories"
      - "Suppliers"

tbls + mkdocs出力例 (ViewPoints)

今後の課題

上記の実装によりデータベースドキュメントの生成に対応しました。現状はコメントが付与されているテーブルはごく一部であり、今後はテーブルのコメントを充実させていく必要があります。

.tbls.yml のエディタ補完

.tbls.yml にデータベースのドキュメントを記述していく方針ですと、フィールド名やcardinalityの値などでエディタの自動補完が効くと便利です。

現状エディタ拡張などはないので、ひとまずVSCodeの YAML Language Server とtblsのソースコードから生成したJSON Schema (https://gist.githubusercontent.com/suzuki-safie/2b56ab4771134d3c801dcd497677f53d/raw/tbls-config.schema.json) を利用することである程度の補完とバリデーションを実現しました。

利用するには YAML Language Serverの導入後、以下の設定をVSCodeの設定に追加してください。

{
  // ...
  "yaml.schemas": {
    "https://gist.githubusercontent.com/suzuki-safie/2b56ab4771134d3c801dcd497677f53d/raw/tbls-config.schema.json":
      [".tbls.yml"]
  }
}

© Safie Inc.