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

f:id:estie:20200810164455p:plain

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

はじめに

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

inside.estie.co.jp


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

f:id:estie:20200809133423p:plain

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

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

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

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

f:id:estie:20200809133035p:plain f:id:estie:20200809133059p:plain

先述の通り、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まで行うツールです。

f:id:estie:20200807193054p:plain
ドキュメント生成の自動化構成

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

SchemaSpy

schemaspy.org

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

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

f:id:estie:20200807165147p:plain
SchemaSpyドキュメント例

Mysql diff

docs.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

Priv Page

github.com

さて、ドキュメントも差分ファイルも取得できました。
取得したファイルは、専用のGithubリポジトリにPushすれば問題なさそうです。

しかし、SchemaSpyのHTMLファイルを閲覧するために、毎回リポジトリをpullするとなると中々面倒です。
社内エンジニアなら誰でもアクセスできるようにホスティングすれば、よりアクセスしやすいドキュメントになります。

ここでまた問題にぶちあたります。

Github Pagesでホストすれば便利だけど、全世界にestieの秘匿情報が公開されてしまう・・・・
他のホスティングサービスを使っても閲覧権限のコントロールが大変そう・・・

そんな悩みを抱えていたところ、あるエンジニアがこのPriv pageというGithub Appを教えてくれました

f:id:estie:20200807173104p:plain
Priv page

Prive pageを入れることで、Github Pagesを同じOrganizationsのGiuhubユーザーのみにプライベート公開することができます。

社内ドキュメントの最大の壁である、セキュリティの課題もこれで解決です。

ECS タスクスケジューラ

docs.aws.amazon.com

あとは定期実行を仕込むだけです。
dockerを定期実行するには、AWS ECSのタスクスケジューラが便利です。

これまでバッチ処理はEC2でcron実行...というレガシーな方法で行なっていましたが、
一度タスクスケジューラで乗せてしまえば、GUIでの設定変更も可能で管理が楽になります。

SchemaSpy + Mysqldiffを取得してGithubにPushするimageを作成して、定期的に実行するように設定します。

これで、いつでも鮮度の高いドキュメントを見ることができますね。

ドキュメントを腐らせない

ドキュメントは「作るコストが高い」「見られていない」とどんどん情報が古くなり、やがてどこかのフォルダの奥底で腐っていきます。

schema-collectorでは、生成部分を全て自動化し、かつブラウザで簡単に参照できる構成にしたことで、「生きた」ドキュメントを作ることができました。

この環境を作ってみて、感じたメリットは、

  • スキーマ確認だけにわざわざデータベースに接続しなくて良い
  • 「ドキュメント作らなきゃ〜」と考える脳のリソースを節約できる
  • 新しくJoinしたメンバーに、スグに渡せる資料がある安心感

というエンジニアのリソース節約でした。

データベースの構成は「調べれば分かること」ですが、

  • 調べるのにかかる時間
  • 調べないと分からない、という感情によるモチベーション低下

は、想像以上にコストだと感じています。

ドキュメントの自動化は、こうしたコストを減らし
本来やるべき実装にリソースを集中できる環境をつくる方法の1つです。

みなさんの会社やチームで、
今回のestieの取り組みが参考になれば幸いです!

おわりに

estieでは、データエンジニアを積極採用中です!
不動産データベースを構築するために、まだまだ取り組みたい課題があります。
一緒に課題解決をしてくれるメンバーを募集しております。
お気軽にご連絡ください!

www.wantedly.com

www.wantedly.com