7th長崎QDGでデータベースのドキュメント化についてLTしてきました

はじめに

こんにちは、クラウド経費本部プロダクト開発部 Guardianグループの@tosite(てっしー)と申します。今回は7th長崎QDGでLTをしてきましたので、その内容について報告いたします。

nagasaki-it-engineers.connpass.com

先日、9/15に長崎市でソフトウェアの品質と開発の技術について語り合う「7th長崎QDG(Software Quality and Development Gathering)」が開催されました。イベント中のみならず休憩時間中にも活発に熱い議論が交わされており、「全ての技術を対象として参加者全員で幅広く議論する」という趣旨の通りのカンファレンスであったように思います。私自身、その規模と熱気、そして何より密度の高い様々なジャンルの発表が行われ、とても刺激を受けました。

2023-10-04追記: 当日の参加レポートが公開されました！よろしければこちらもご覧ください！ moneyforward-dev.jp

登壇内容

今回、登壇する機会をいただき、「ER図クエスト過ぎ去りしドキュメントを求めて〜複雑性に眠る秘宝〜」というタイトルでLTをしてきました。

登壇資料では、新しい職場で新しいチームに配属された際に必要となるドメイン知識について、それをどのように獲得するかについて焦点を当てました。この課題、配属されて真っ先に遭遇するものであると言っても過言ではないと思いますが、どのように習得していくかについて悩まれる方も多いのではないでしょうか。

私は新しいプロジェクトに参画した際は、まずデータベースのテーブル構造に着目します。すでにあるドキュメントと突き合わせながら読み込むことで、素早く仕様理解を進めることができます。更には、理解した内容やチームメンバーにヒアリングした内容をドキュメントに起こすことで、得られた暗黙知を形式知に昇華することが可能になります。

しかしながら「ドキュメント化」には課題も存在します。特に感じていることとして、「ドキュメントの継続的メンテナンス」と「特定の視点から見たドキュメントの不完全性」の2点が挙げられます。前者については継続的メンテナンスの大変さを味わったことがある方が多いかと思います。後者についてはデータベースを特定の視点から切り取って見た視点(例えば契約に紐づく全てのリレーションテーブルなどのこと。以下、ビューポイントと呼ぶ)のことです。

そこで私はtblsというOSSを導入するというアプローチを取りました。

tblsというOSSについて

tbls ( is pronounced /ˈteɪbl̩z/. ) is a CI-Friendly tool for document a database, written in Go.

github.com

tblsとは、端的に言えば「データベースドキュメント自動生成ツール」です(開発者の方は「Document as Code」というキーワードで説明されています)。データベーススキーマのドキュメントを様々な形式で出力することができるほか、CIに組み込みやすく、データベースのLinterやドキュメントの差分検知ツールとしても機能します。

ドキュメントの継続的メンテナンスについてのアプローチとして、CI(Continuous Integration)にtblsを組み込むことで最新のデータベースとドキュメントの整合性を自動的に検知できるような仕組みを整えました。これはCIに使用されるデータベースが最新のものになる性質を利用しています。ドキュメントがメンテナンスされていないことを検知してCIを落とすことで最新の情報に追従していない時にCIが教えてくれるようになったため、ドキュメントが自然と最新の状態に保たれるようになりました。

特定の視点から見たドキュメントの不完全性については、tblsのラベル機能を利用しました。機能ごとのテーブル群にラベルを付与し、グルーピングしたものを出力することでテーブル構造をビューポイント単位でより明確に表現することが可能になります。

このような仕組みを取り入れることで、自身の知識習得に留まらずチーム全体の資産へと昇華することができます。しかしながら、まだ全てのドキュメントが整備されたわけではありません。今後はビューポイントの整備などを通して継続的にドキュメントの整理に取り組んでいくことで、更に質を高めて行きたいと考えています。

余談ですが、登壇後に参加者数名から「tblsというツールを初めて知りました」「使ってみたいです」といったポジティブなご意見をいただけました。普段やっている取り組みをアウトプットすることでフィードバックがいただけるのは本当に嬉しいですね！