ECブログリレーツイートEC事業部でシニアエンジニアリングリードをしているkenchanです。コードリーディング会に参加して1年経ちましたでした。カラーミーショップの開発チームでは、2020年末にデータベースドキュメンテーションツールとしてtblsを導入しました。本記事では、tblsの機能や導入の狙いから、実際の移行のプロセスをふりかえり、最後に今後やっていきたいことについて紹介します。データベースドキュメントの継続的なメンテナンスに課題を感じている方の参考になれば幸いです。tblsとは何かk1LoW/tblsは、ホスティング事業部の@k1LoWが開発、メンテナンスをしているデータベースのドキュメンテーションツールです。tblsを使うことで、MySQLやPostgreSQLなどのRDBMSはもちろん、BigQueryやRedshiftなど様々なDBMSのスキーマ情報からドキュメントを生成することができます。実行ファイルはワンバイナリのため環境への依存が少なく、CIなどへの組み込みが容易という特徴も持っています。実際に生成されるドキュメントはリポジトリにあるsampleにある通り、Markdown形式のテーブル定義とSVG形式のER図です。前述の特徴をうまく活用することで、以下のような効果が得られると考えています。DBスキーマと乖離しない生きたドキュメントにできる制約がドキュメントに反映されるため堅いDB設計のインセンティブが高まる複数のDBMSでドキュメントのフォーマットを統一できる1つ目は言わずもがな、ドキュメントの生成元はデータベースのスキーマ情報になるので、ドキュメントの更新忘れを仕組みで防ぐのが容易になります。2つ目については、外部キー制約を設定することでER図がリッチになりますし、enum型など制約の強い型を使うことがドキュメントを充実させることに繋がります。堅いDB設計をすることがデータの堅牢性を高めるだけでなく、ドキュメントのメンテナンスコストを削減することにもなるということです。最後の効果は、現代の大規模アプリケーションが複数のDBMSを使い分けていることに起因します。読者のみなさんも、アプリケーションのデータを保存するのはRDBMSで、分析基盤としてRedshiftやBigQueryを利用するというケースが多いのではないでしょうか。いった状況においては、ドキュメントのフォーマットや書き方が統一できるというのは大きなメリットになりえます。以上の効果を期待し、カラーミーショップではデータベースドキュメントツールとしてtblsを導入することを決めました。tbls以前のカラーミーショップのDBドキュメントカラーミーショップでは、tbls導入前もデータベースドキュメントがもちろんありましたが、DDLに自然言語でコメントをつける形式で、フォーマットが決まっているわけではありませんでした。実際のドキュメントの一部をお見せすると、以下のようなテーブル単位のドキュメントが用途ごとにいくつかのMarkdownファイルに分かれて存在している状態でした。ROW_FORMAT=COMPRESSED;...ドキュメントの作成や更新は、スキーマ更新をする開発者とレビュアーに頼っており、カラムの増減や取りうる値の更新などが漏れてしまう場合がありました。開発者であればコードや変更履歴を追うことでドキュメントと実態の差異に気づくこともできますが、分析などのためにデータを閲覧しているディレクターやカスタマーサポートにとってはドキュメントだけが頼りであり、これが継続的にメンテナンス出来ていないことは事業部全体の課題でした。tblsへの移行プロセス前述の通り、移行前にも価値のあるドキュメントは存在していたため、これをうまくtblsへと移行する作業を行うことにしました。これは以下のような手順で進めました。既存のドキュメントを.tbls.yml形式に変換するtblsは、DBのスキーマから取得した情報だけでなくYAMLファイルを使ってドキュメントに情報を追加できます。README.mdにあるCommentsやRelationsのような情報を記述することで、メタデータや制約がなくてもドキュメントの情報量を増やせます。既存のドキュメントをこの方法で移行することにしました。前章で紹介したMarkdown形式のドキュメントは、明確なフォーマットはありませんでしたが緩やかな共通点はありました。Errorになっているのが無視できない量あったため、ファイルを行単位で読み込んでパースするスクリプトを自作しました。そのスクリプトによって約400テーブルのドキュメントをYAML化した後、いくつかのエッジケースを手作業で移行しました。tblsでドキュメントを生成して差異が出たところを修正する最初の作業では、DBスキーマとドキュメントの乖離は考慮していませんでした。そのため、生成した.tbls.ymlと最新のスキーマからドキュメントの生成を行って差異がないかを確認しました。tblsは、YAMLのコメントと実際のデータベースに差異があるときはエラーとして報告してくれます。これを繰り返し、古くなっているドキュメントを1つ1つ直していきました。幸運にも、テーブルやカラムの有無に関する古い情報は両手で足りる程度でした。最終的な.tbls.ymlが4000行を超えてしまっているため、k1LoW/tbls-buildを使ったファイルの分割を検討しています。tblsによるドキュメント更新方法を周知する最後に、tblsをつかったドキュメントの作成・更新をするためのコマンドとドキュメントを作成しました。カラーミーショップの開発環境はすべてDockerコンテナを使うようになっているため1、まずはリポジトリにある.tbls.ymlとDockerコンテナとして動いているDBからドキュメントを作成・更新できるようにしました。実際に運用を始めてみたところ、一時的に検証のために追加したカラムやインデックスの差分が出るケースもあったため、ドキュメント生成用のDBを都度用意してスキーママイグレーションを最初から実行するという運用をしています。Makefileは以下のようなイメージです。Railsを利用している方はなんとなくイメージできるかと思います。-fまとめと今後の展望この記事では、2020年末に実施したtbls導入の狙いと実際のプロセスを紹介しました。カラーミーショップでは、開発者以外もRedashを利用してデータの検索・分析を行うため、誰もが安心して使える生きたドキュメントを、妥当なコストでメンテナンスし続ける仕組みが必要とされていました。tblsは社内の実績も豊富で、前述の課題を解決するための最適なツールだと考えています。一方で、改善できる点はまだまだあります。開発プロセスへ組み込む(CI/CD)カラムに対するドキュメントの網羅率の向上させるログ基盤として利用しているBigQueryに導入するこれらの施策を進め、カラーミーショップの開発ドキュメントの拡充と、開発組織全体のデータ分析能力の向上を目指していきたいと思います。エンジニア新卒採用に関する情報をまとめたページも公開中!ツイート書いた人kenchanEC事業部シニアエンジニアリングリード。Rubyとアジャイルなソフトウェア開発が好物。