データベースを文書化する方法
（注：これは データベース構造をどのように文書化していますか？ に近いとわかりますが、同一とは思いません。）
私は文字通り何百ものテーブルとビューを持ち、すべて母音がほとんどなく、ドキュメンテーションのない不可解な名前を持つデータベースのある場所で仕事を始めました。また、データベーススキーマに無償で変更を加えることも許可されておらず、自分のマシンでテスト用のもの（吹き飛ばされて定期的に再作成される）以外のデータベースに触れることもできないため、誰にも役立つコメントを追加することはできません。
「Toad」を使用してERダイアグラムを作成しようとしましたが、それを48時間実行したままにすると、まだ何も表示されず、コンピューターを戻す必要がありました。私は他の最近の採用者と話をしていたので、特定のテーブルやその列の意味がわからないときはいつでも、開発者のwikiで更新することを提案しました。
それで、これを行う良い方法は何ですか？テーブル/ビューとそれらの列をリストし、私たちが行くにつれてそれらを埋めるだけですか？私が手に入れた基本的なツールは、Oracleの「SQL Developer」であるToad、MS Office、およびVisioです。
私の経験では、ER（またはUML）ダイアグラムは最も有用なアーティファクトではありません-多くのテーブルでは、ダイアグラム（特にリバースエンジニアリングされたもの）は、誰も何も学習しない大きな複雑な混乱であることがよくあります。
私のお金では、人間が読める優れたドキュメント（システムの小さな部分の図で補足されている場合があります）を使用すると、最大限の燃費が得られます。これには、各テーブルについて以下が含まれます。
- テーブルの意味と機能的な使用方法の説明（UIなど）
- 明らかでない場合、各属性の意味の説明
- このテーブルから他のテーブルへの関係（外部キー）の説明、およびその逆
- 追加の制約および/またはトリガーの説明
- まだ十分に文書化されていない場合、テーブルに触れる主要なビューとプロシージャの追加説明
上記のすべてで、文書化のために文書化しないでください-明白なことを再説明する文書は、人々の邪魔になります。代わりに、最初はあなたを混乱させたものに焦点を合わせ、数分かけて本当に明確で簡潔な説明を書きます。それはあなたがそれを熟考するのを助け、大規模にこれらのテーブルに初めて出会う他の開発者を助けます。
他の人が言及したように、これを管理するのに役立つさまざまなツールがあります Enterprise Architect 、 Red Gate SQL Doc 、およびさまざまなベンダーの組み込みツール。ただし、ツールのサポートは役立ちますが（さらに大きなデータベースでは重要です）、understandingand説明データベースの概念モデルが真の勝利です。その観点から、テキストファイルでそれを行うこともできます（Wiki形式でそれを行うと、数人がそのドキュメントに段階的に追加できるようになります-だから、誰かが何かを理解するたびに、成長している身体にそれを追加できます文書の即時）。
私たちのチームでは、従来の大規模なOracleおよびSQL Serverデータベースを文書化するための便利なアプローチを採用しました。 Dataedo を使用して、データベーススキーマ要素（データディクショナリ）を文書化し、ERD図を作成します。 Dataedoにはドキュメントリポジトリが付属しているため、すべてのチームが最新のドキュメントをオンラインでドキュメント化して読むことができます。また、データベース（OracleコメントまたはSQL Server MS_Description）に干渉する必要はありません。
まず、スキーマ（すべてのテーブル、ビュー、ストアドプロシージャと関数-トリガー、外部キーなど）をインポートします。次に、論理ドメイン/モジュールを定義し、すべてのオブジェクトをそれらにグループ化（ドラッグアンドドロップ）して、データベースの小さなチャンクを分析および操作できるようにします。モジュールごとに、ERDダイアグラムを作成し、トップレベルの説明を記述します。次に、テーブルとビューの意味を発見したら、それぞれの簡単な説明を書きます。各列に対して同じことを行います。 Dataedoでは、各オブジェクトと列に意味のあるタイトルを追加できます。オブジェクト名があいまいまたは無効な場合に役立ちます。 Proバージョンでは、外部キー、一意のキー/制約、およびトリガーを説明できます。これは便利ですが、データベースを理解するために必須ではありません。
UIを介してドキュメントにアクセスするか、PDFまたはインタラクティブHTML（後者はProバージョンでのみ使用可能）にエクスポートできます。
ここで説明するのは、1回限りの仕事ではなく、継続的なプロセスです。データベースが変更された場合（新しい列、ビューなど）、ドキュメントを定期的に同期する必要があります（クリックとDataedoを組み合わせてください）。
サンプルドキュメントを参照してください： http://dataedo.com/download/Dataedo%20repository.pdf
文書化プロセスに関するいくつかのガイドライン：
図：
- 図を小さく読みやすいものにしてください-重要なテーブル、リレーション、列のみを含めてください-全体像を理解するのに意味のあるもののみ-プライマリ/ビジネスキー、重要な属性と関係、
- 図のキーテーブルに異なる色を使用し、
- モジュールごとに複数の図を作成できますが、
- 最も重要なテーブル/ほとんどの関係の説明に図を追加できます。
説明：
- 明らかなことを文書化しないでください。document.date列に「文書の日付」という説明を書かないでください。追加する意味がない場合は空白のままにしてください。
- テーブルに保存されているオブジェクトにタイプまたはステータスがある場合は、テーブルの一般的な説明にそれらをリストするとよいでしょう。
- 予想される形式を定義します。テキストフィールドに保存されている日付の「mm/dd/yy」、
- すべての既知の/重要な値とその意味をリストします。ステータス列には、「ドキュメントのステータス：A –アクティブ、C –キャンセル、D –削除済み」などがあります。
- テーブル（データを挿入/更新するためのデータと関数/手順の読み取りに使用する必要があるビュー）にAPIがある場合は、テーブルの説明にリストし、
- 行/列の値の取得元（手順、フォーム、インターフェイスなど）を説明し、
- 使用すべきではない列には「[非推奨]」マーク（または同様）を使用します（タイトル列はこれに役立ちます。説明フィールドで代わりに使用するフィールドを説明してください）。
考慮すべきことの1つは、DBMSに組み込まれているCOMMENT機能です。 DBMS自体のすべてのテーブルとすべての列にコメントを付けた場合、ドキュメントはデータベースシステム内にあります。
COMMENT機能を使用しても、スキーマ自体は変更されず、USER_TAB_COMMENTSカタログ表にデータが追加されるだけです。
DB定義には Enterprise Architect を使用します。ストアドプロシージャ、トリガー、およびUMLで定義されたすべてのテーブル定義が含まれます。プログラムの3つの素晴らしい機能は次のとおりです。
- ODBC接続からUML図をインポートします。
- DB全体のSQLスクリプト（DDL）を一度に生成
- DBのカスタムテンプレートドキュメントを生成します。
UMLツール内でクラス/テーブル定義を編集し、画像が含まれるドキュメントで完全に記述的なものを生成できます。自動生成されたドキュメントは、MSWordを含む複数の形式にすることができます。スキーマに含まれるテーブルは100未満であり、非常に管理しやすいです。
開発者として10年以上の間、他のツールにこれほど感銘を受けたことはありません。 EAは、Oracle、MySQL、SQL Server（複数バージョン）、PostGreSQL、Interbase、DB2、およびAccessを一挙にサポートします。私が問題を抱えたときはいつでも、彼らのフォーラムは私の問題に迅速に答えてくれました。強くお勧めします！！
DBの変更が入ったら、EAで作成し、SQLを生成して、バージョン管理（svn）にチェックインします。ビルドには Hudson を使用し、チェックインされたSQLを変更したことがわかると、スクリプトからデータベースを自動ビルドします。
（ 私の別の回答からほとんど盗まれた ）
データベースのドキュメントへのアプローチ方法に関する良い投稿を次に示します。 http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and -how /
ウィキソリューションは、ハイパーリンクと共同編集をサポートしていますが、ウィキは、それを整理し、最新の状態に保つ人々と同じくらい優れています。使用するツールに関係なく、ドキュメントプロジェクトの所有権を取得する誰かが必要です。その人は詳細を記入するために他の知識のある人を巻き込むかもしれませんが、一人は情報を整理する責任があります。
ツールを使用してリバースエンジニアリングによってERDを生成できない場合は、TOADまたはVISIOを使用して手動で設計する必要があります。
何百ものオブジェクトを持つERDは、多くのボックスや行では読み込めないため、おそらく開発者向けのガイドとしては役に立ちません。非常に多くのオブジェクトを持つデータベースでは、それぞれ数十個のテーブルとビューの「サブシステム」がある可能性があります。したがって、ツールがあなたのためにそれを行うことを期待するのではなく、これらのサブシステムのカスタム図を作成する必要があります。
また、テーブルのグループが1つの図で単一のオブジェクトによって表され、そのグループが別の図で展開される擬似ERDを設計することもできます。
単一のERDまたはERDのセットでは、この複雑なシステムを文書化するのに十分ではありません。OOシステムを文書化するには、クラス図で十分です。文書を作成する必要があります。 、イラストとしてERDを使用します。各テーブル、各列、およびテーブル間の関係（特に、そのような関係が参照整合性制約によって表されるのではなく暗黙的である場合）の意味と使用法のテキスト説明が必要です。
これはすべて大変な作業ですが、それだけの価値があります。スキーマが文書化されている明確で最新の場所があれば、チーム全体がそれを活用できます。
この答えは、上記のKieveliを拡張したもので、私はそれを支持しました。 EAのバージョンがオブジェクトロールモデリング（概念設計対論理設計= ERD）をサポートしている場合、それをリバースエンジニアリングし、モデルに表現力豊かな表現を加えます。
安くて軽いオプションは、VisiomodelerをMSから無料でダウンロードし、同じことをすることです。
ORM（ORMDBと呼びます）は、BLオブジェクトと関係について、IS以外の利害関係者とのデータベース設計の対話をサポートおよび促進する唯一のツールです。
リアリティチェック-DDLを生成する途中で、完全に停止したERDフェーズを通過します。そうではありません。おそらく、自分で設計したERDの弱点を示すでしょう。
ORMDBは、ツールがより概念的であるほど、市場は小さくなるという原則の典型的な例です。女の子はただ楽しみたいだけで、プログラマーはただコーディングしたいだけです。
データベースをエンドユーザーに説明することが主な目標である場合 Ooluk Data Dictionary Manager が役立つことがわかります。これは、テーブルと列に説明を添付し、それらの説明で全文検索を可能にするWebベースのマルチユーザーソフトウェアです。また、ラベルを使用してテーブルを論理的にグループ化し、それらのラベルを使用してテーブルを参照することもできます。テーブルと列にタグを付けて、データベース全体で同様のデータ項目を見つけることができます。
このソフトウェアでは、APIを使用して、テーブル名、列名、列データ型、外部キーなどのメタデータ情報を内部リポジトリにインポートできます。 JDBCデータソースのサポートは組み込みで提供され、APIソースがASL 2.0で配布されるため、さらに拡張できます。多くのRDBMSからCOMMENTS/REMARKSを読み取るようにコーディングされています。インポートされた情報はいつでも手動で上書きできます。テーブルと列について保存できる情報は、カスタムフィールドを使用して拡張できます。
データディクショナリマネージャは、リレーショナルデータベース用に特別に設計されていないため、テーブルと列の代わりに「データオブジェクト」と「属性」の用語を使用します。
ノート
- トリガー、インデックス、統計などのデータベースの技術的側面を説明する場合、このソフトウェアは最適な選択肢ではありません。ただし、ハイパーリンクのカスタムフィールドを使用して、技術的なソリューションとこのソフトウェアを組み合わせることができます。
- ソフトウェアはERDを生成しません
開示：私はこの製品を開発している会社で働いています。
同じ船に乗っている仲間の開発者と仕事をする余裕があるので、必要な情報を最も簡単に伝えることができると感じるものを彼らに尋ねることをお勧めします。私の会社には100を超えるテーブルがあり、上司はすべてが接続する特定のセットテーブルのERDをくれました。また、1つの大規模なERDを、より小さく管理しやすいERDの束に分割してみてください。
まあ、写真は千の言葉を伝えるので、テーブル間の関係を一目で見ることができるER図を作成することをお勧めします。これはテキストのみの説明では困難です。
データベース全体を1つの図で行う必要はなく、セクションに分割します。私たちは職場でVisual Paradigmを使用していますが、EAはERWINと同様に優れた代替手段であり、同様に優れたものが他にもたくさんあることは間違いありません。
忍耐がある場合は、htmlを使用して表と列を文書化すると、文書へのアクセスが容易になります。