データベースのドキュメント管理を自動化した話

こんにちは、今回はデータ基盤構築を担当しているmarushoがお送りします。
今日はestieで実践しているデータベースのドキュメント管理方法をご紹介します。

はじめに
独自成長していくデータベースたち
失われたドキュメント
どうすれば低コストなドキュメント管理ができるのか
そして生まれた、schema collectorという自動化ツール
ドキュメントを腐らせない
おわりに

はじめに

estieはオフィスを中心とした不動産データを取り扱うスタートアップ企業です。
estie（オフィス探しサービス）とestie pro（不動産事業者向けデータプラットフォーム）の2つのサービスを運営しています。
詳しくは、こちらの記事をご覧ください。

inside.estie.co.jp

estieでは、不動産に関するデータの共通データベースを保有しています。
各サービスは共通データベースと一部同期することで、最新のデータを提供できるようにしています。
(またRDBMSは主にMysqlを利用しています)

ところが、開発運用しているとこんな悩みが出てきます。

プロダクトのアップデートで、毎週のようにデータベースがMigrationされる...
プロダクトごとに必要なカラムを追加するので、共通テーブルとの構成が乖離していく...
新しくJoinしたメンバーが見るデータベースのドキュメントが無い....

スタートアップの速さを意識した開発と、
複数プロダクトを運営しているゆえに、共通構成の保持が難しいことに気がつきました。

独自成長していくデータベースたち

先述の通り、estieは2つの不動産サービスを運営しています。
estieとestie proは同じオフィス不動産を扱うサービスですが、全く異なるサービスです。

そのため、不動産の共通テーブルを持ちながらも、サービスごとに実装したいテーブル構成が違うということになります。

たとえば片方のサービスでAカラムが追加され、もう片方ではBカラムが追加される。
そうなると共通テーブルはAとBを持つ必要があります。

時には片方のサービスにAカラムが追加され、もう片方がそれを知らず少し定義が違うA'カラムを追加しちゃったり・・・

こうして少しずつ共通構成からずれていき、データの更新がままならない状態に…！

この事態の対応はひとまずマンパワーで解決したのですが、再発防止のために対策が必要です。

最も効果的なのは共通テーブルの定義編集を禁止することです。
しかし、この方法はプロダクトの設計にも影響が出て、開発を遅延させるさせる可能性があったり、予期せぬバグも引き起こしかねません。
少なくとも、共通テーブルと独自テーブルの分離が完了してから行うべきと判断しました。

次に、「そもそも各データベースの構成が分かるドキュメントが無いから魔改造されていくのでは？」という仮説が出てきました。

失われたドキュメント

以前のestieは、データやAPI層などデータベースに関わる部分は、3名のエンジニアで開発を進めていました。

そのため、わざわざドキュメントを作成しなくても定期的なコミュニケーションで解決していました。

しかし、会社の規模が大きくなるにつれて(嬉しいことに)メンバーが増えたことで、その共通認識が取れていない部分が出てきていたのです。

新しくJoinしてくれたメンバーが、estieの肝であるデータの構成を知る術が無い状態はあまりにも不親切です。
とはいえ、ご存知の通りドキュメントの保守は想像以上にコストがかかるのです。

estieでも、何度か社内wikiやExcelファイルで仕様ドキュメントを作成しましたが、
メンテナンスが間に合わず、古い情報によって混乱させてしまうこともあり、結局ほとんど残っていません。

どうすれば低コストなドキュメント管理ができるのか

日々変化するデータベース構成をまず「可視化する」ために、社内のエンジニアでアイディアを出し合いました。
これらの課題を解決するツールは無いか？と調査も含め行なったところ、以下のようなツールで実現できそうでした。

テーブル構成をエクセルで書くのは辛い、自動生成したい

=> SchemaSpyを使おう

スキーマファイルだけじゃなくて、差分も見たいよね

=> Mysql diffで取得しよう

出力したスキーマファイルを社内で共有できるようにしたいよね

=> リポジトリにpushしちゃえばGithub Pagesで閲覧できそう

自動化して常に最新に保ちたいよね

=> Docker化してECS Schedulerで動かそう

つまり、こんな流れで実現できそうなのです。

1. 定期的にSchemaspyとMysql diffがデータベースにアクセスし、最新の構成を取得
2. Github の専用のリポジトリにPush
3. Github Pagesで社内エンジニアのみ閲覧できるように公開

この環境を作ることで、エンジニアなら誰でも、いつでも、全てのデータベースの構成を把握することができます。

そして生まれた、schema collectorという自動化ツール

SchemaSpy + Priv Page + Mysql diff + ECS

このツールたちを組み合わせて、schema collectorというドキュメント自動生成ツールが生まれました。
github.com

schema collectorは、指定したDBにアクセスをしてスキーマを取得しドキュメント化・githubリポジトリにpushまで行うツールです。

利用したツール類について、簡単に紹介していきます。

SchemaSpy

schemaspy.org

SchemaSpy は、データベースにアクセスして自動でHTMLドキュメントを生成するツールです。
Java製ですが、docker版もあるため簡単に動作させることができます。

生成されるドキュメントはHTML形式なので、そのままホスティングすればブライザで閲覧が可能です。
このような綺麗なドキュメントでデータベーススキーマを確認することができます。

Mysql diff

https://docs.oracle.com/cd/E17952_01/mysql-utilities-1.5-en/mysqldiff.htmldocs.oracle.com

SchemaSpyで最新のスキーマ定義をグラフィカルに表示できました。
一方で、日々行われるMigrationで発生する差分も取得しておきたいですよね。

Oracle製のMysqlUtilitiesにはmysqldiffというCLIツールが含まれており、
2つのDDLから差分ファイルを生成することができます。
そのため、最新のスキーマ取得前後のDDLを比較することで、このような差分ファイルを作成することができます。

*** 60,66 ****
  CREATE TABLE `samples` (
!   `id` bigint(20) NOT NULL AUTO_INCREMENT,
    `column_1` float DEFAULT NULL,
--- 60,66 ----
  CREATE TABLE `samples` (
    `id`  bigint(20) NOT NULL AUTO_INCREMENT,
!   `new_column` varchar(255) DEFAULT NULL,
    `column_1` float DEFAULT NULL,

そのまま実行すると、auto incrementの数字の差分がファイルに出てしまうので、
こちらの記事で紹介されている方法で握りつぶしています。
kakakakakku.hatenablog.com