実は難しいドキュメント管理
こんにちは。小崎です。
当社にも様々な課題がありますが、今回はドキュメント管理について取り上げてみたいと思います。ただし、ドキュメント管理全般ではなく、おそらくどの会社でもあると思われるデータベースのスキーマ管理（テーブル定義）にフォーカスします。会社の規模や体制等によって異なるとは思いますが、ある程度共通の課題があるかと思います。
課題
まずは課題について整理したいと思います。
フォーマットがバラバラ
テーブル定義一つとってもなかなか全体で揃えるのが難しいです。おそらく日本の開発であれば、エクセルで作られるあのフォーマットを想像できる方が少なくないかと思います。 が、同じフォーマットで揃えるのはなかなか難しいです。と言うのは、
- 開発する会社が異なる。
- 同じ会社だけれども、その人が良いと思うフォーマットが違う。
- そもそもルールがない。もしくはルールはあるけど、周知されていない・知らない。
と言った理由が考えられます。
どこにあるのかわからない
これもよくあるのでは？と思います。当社にも似たようなシーンはあります。
要因としては次のことが考えられます。
- ファイルサーバー等に所定のフォルダはあるが対象のテーブル情報がなく、プロジェクト用のフォルダにある。
- 所定のフォルダがあることを自分だけ知らない。
- そもそも明示されたルールがなく、暗黙的に運用されている。あっても周知されていない。たまたま知らない。
記載が古い
データベースの定義は一度運用に入れば、テーブルがなくなると言うことは少ないと思いますが、カラム追加やパフォーマンスチューニングでIndexが追加されたと言うことはよくあると思います。初期開発後の追加開発においてはシステムだけでなく、維持対象のドキュメントも更新する必要がありますが、これを漏れなく長期に渡って維持するのはなかなか大変なことです。 要因はいくつも考えられますが、以下のようなことがあるのではないかと思います。
- 既存でテーブル定義のドキュメントがあると認識していなかった。
- プロジェクト用のフォルダに更新版を作ってあるが、共有フォルダに配置することが漏れた。
- 時間が足りず、ドキュメントの更新が間に合わなかった。
テーブル定義限った話ではないですが、ドキュメントと現物の乖離はリスクとしては常に存在します。熟練の開発者であれば、ソースコードやデータベースそのものがどうなっているのかの確認は欠かさないのではと。
ソリューション
上記課題の中で最も重たい「記載が古い」を中心に考えました。
開発ルール整備や周知等はなんどもやってきましたが、長期的に人力ベースで状態を維持するのは困難でした。また、間違っていないと言うことを担保するには仕組みが必要で、人間が注意すると言うアプローチは無理筋と判断しました。また、割り切りとして、管理対象は長期に渡って管理するテーブル定義であって、開発プロジェクト中に作成されるテーブル定義は対象に含まないとしました。ドキュメント管理全般について言えると思いますが、長期に渡って役に立つ必要があるドキュメントなのか、短期的に役に立てばよいドキュメントなのかを区別することは有用です。基本的に開発プロジェクトチームが作成するドキュメントは、圧倒的に短期のものが多く、プロジェクトチームは、要件を満たす成果物を期限・予算内にリリースすることがゴールであるため、長期的なドキュメントを整備するモチベーションが生まれにくいと言う背景も認識すべきでしょう。
定義はDBから引っ張ることで古くさせない
前述の認識から、手でエクセルを維持するのではなく、データベースそのものから定義情報を抽出することで解決することにしました。こうすることで、絶対に古くならない・ズレないことが担保できます。
また、ルールは必要なのですがルールだけで解決を考えると、肥大化・細かすぎるルールとなり、ルールを守るのは人間と言うことを考えると、ルールの改善・周知徹底だけは現実的とは言えません。その他の課題である「フォーマットがバラバラ」、「どこにあるのかわからない」を満たすため、独自にアプリケーションを開発しました。
ONIGIRI-DB
アプリケーションの名前に意味はないのですが、当社DBAたっての希望でONIGIRI-DBと命名されました。
一番の肝は、データベースから定義情報を抽出し表示する仕様とし、定義自体は入力／修正させないと言う点です。バッチにて定義情報を抽出しデータを解析した上で、情報を整理して画面に表示します。現在は、OracleとSQLServerに対応しています。
メイン画面
多数マスキングがあり、見づらくてすみません。
左ペインに、データベース→インスタンス→スキーマ→テーブルと表示されます。左ペインは折り畳む事が可能です。
右ペインには選択されたテーブルに関する
- テーブル名等の情報
- カラム
- 索引（インデックス）
- 制約
が表示されます。
残念なところなのですが、定義はデータベースから取ると言うこともあって論理名は自身で設定する必要があります。（無論、入力されれば全員で共有することが可能です）
備考欄は任意の事項が入力可能です。
履歴の表示が可能
ユーザーが任意で入力した情報や、データベースから取得された情報の変更（列の追加など）は、履歴を確保する機能を有しています。
実装についてはGitをうまく使っているので、内部の構成・実装については後続の記事で紹介できればと考えています。
右ペイン ヘッダーの右はそれらの表示切り替えです。
- Blame いつ時点の情報かが表示されます
- Diff 指定テーブル間の相違点が表示されます。例：開発DBと本番DB間での相違点
コード値定義
エクセル管理より圧倒的に優れていると自負してますｗ
コード値（区分値）の管理機能も実装しています。上の画面は定義の登録編集画面となっていて、ここで定義したコード定義を該当のカラムにリンクすることができます。紐付情報欄では、この定義がどこにリンクされているかの一覧で見ることができます。
当然ではあるのですが、ここの入力も人が行わねばならないと言う点はあります。また、カラムの備考欄にコード定義を入れてしまうユーザーもいるので、時々、使い方の周知をしないとなと思っています。
全項目検索
テーブル名やカラム名だけでなくユーザー入力値含めた全項目に対するキーワード検索が可能です。
一番の動機はやはり、調査で有用と言う点です。同じカラム名を持ったテーブルはどれ？など調べることが多々あるかと思います。
本アプリは当社の開発パートナー様と一緒に開発しました。この検索機能も、Gitをうまく使った実装のおかげです。
終わりに
本アプリを開発する前に世の中のツールは探してみました。DB定義を見るものは色々とあるのですが、情報を付加してチームで共有すると言うようなドキュメント管理視点を有したものは見つけられませんでした。また、この手の製品は、ユーザー数課金が多くランニングが高額になってしまう難点があります。本アプリはAWSでホストしており、何人使おうがランニングコストはAWS費用だけです。
URLさえ知っていれば、ブラウザでさっと開けますのでエクセルで開くよりだいぶお手軽です。初期Verリリースから1年ほど経過していますが、当社内ユーザーからの評判もまずますと言った状況で、本記事の冒頭で掲げた課題はクリアできているのかなと考えています。
運用面の機能や最近使い始めたMySQLへの対応など、追加したい機能はありますので、少しずつ改善できればと思います。
おそらくどの会社でもデータベースのテーブル定義管理はあると思いますので、人前に出しても恥ずかしくないレベルに達したら公開できるといいなぁと個人的には思っています。
