note社のデータベースのドキュメントを自動生成する仕組みをつくってみた
どうもnote株式会社のSREのみーにです！
私の素性を知らない方は先に自己紹介ページや入社エントリなどを参照ください… :pray:
最初に結論(作ったもの)
SchemaSpyをGithub Actionsから定期実行できるworkflowを作成しました！
指定したデータベースのドキュメントを日次で自動生成&更新することができる仕組みです。
以下リポジトリからどなたでも利用できます！
この記事では、noteでSchemaSpyをGithub Actionsから定期実行できるworkflowが必要になった背景をお話ししていきます！
なぜやったか: 前提
noteでは、データベースを以下のような形で運用しています。
AWS Auroraでデータベースを運用中
Rails(Active Record)のmigration機能でテーブル定義を変更している
migrationによるテーブル定義変更は、機能の要請次第である程度自由に行える
コードレビューはあるが、テーブル定義の変更に際して特別な承認や周知の手続きはない
特にテーブル定義については、noteのサービス規模拡大や機能拡張に伴って拡大・複雑化を続けていました。
なぜやったか: 課題
データベースが拡大・複雑化を続ける一方で、
noteではデータベース全体のドキュメントが作成されていませんでした！
具体的には、以下のような状況でした。
各機能・開発チームごとに必要なタイミングで都度テーブル定義表/ER図などのドキュメントを作成していた
このドキュメントは作成者がかかわる/関心のあるテーブルのみを記載している場合が多く、断片的なドキュメントがいくつも存在している状態になっていた
データベース全体の状況を確認したい場合は、以下いずれかを参照してテーブルを1つ1つ見ていくしかない状態だった
Railsのmigrationファイル
Redashなど、データベースを参照しているツール
データベースを直接参照(最終手段で、できれば避けたい)
各機能・開発チームのレベルではこの状況でも大きな問題は起きていませんでしたが、
SREチームでnoteをEKS環境に移行していく過程でnoteの現状を包括的に読み解く際、データベース全体のドキュメントがないために苦労する場面が出てきました。
特に社歴の浅い私は既存のドキュメントもほとんど確認できていなかったため、とりあえずデータベースの全貌がわかる資料を必要としていました。
(noteの新入社員のみなさんも同じ課題を抱えていたのではないでしょうか！)
やったこと
SchemaSpyとGithub Actionsを利用して、データベース全体のドキュメントを自動生成&更新できるようにしました。
作ったものがこちらになります！
このGithub Actionsを実行すると、上記のようなhtmlドキュメントが生成されます。
特に、画面右側のSearch欄にデータベース名を入力すると前方一致でテーブルの検索ができる機能が便利です！
noteでは、このhtmlドキュメントを社内用のS3に配置し、静的ウェブサイトホスティングの機能でwebページとして社内限定公開しています。
これによって、社内ドキュメントやGithub Issueからこのドキュメントのリンクを貼る形でテーブル定義を参照できるようになりました！
注意点として、インターネットに公開していないデータベースにGithub Actionsからアクセスする場合はself-hosted runnerを利用する必要があります。(Github提供のrunnerでは、インターネットに公開していないリソースには到達できません)
noteではECSをself-hosted runnerとして利用しています！
アーキテクチャの全貌は上記のようになります。
これで、当初の目標であったnoteのデータベース全体のドキュメントが手に入りました！
ドキュメントは自動で更新されるためメンテも必要なく、継続的な資料として全社で活用できる状態になったと思います！
まとめ
データベースのドキュメントをSchemaSpyとGithub Actionsで作成&更新する方法について紹介しました。
データベースのドキュメントがなくて苦しんでいるエンジニアの方や、かつての私のようにテーブル定義表を手作業で更新する作業に一日の大半を費やしているエンジニアの方はぜひお試しください！
今回作成されたドキュメントの実物を確認したい！という方はこちら↓