sql - データベース構造をどのように文書化しますか?

Question

多くのデータベースシステムでは、テーブルやフィールドのコメントや説明を許可していません。では、テーブルやフィールドの目的を文書化するには、適切な命名規則を使用することは別として、どうすればよいでしょうか?

(今のところ、データベース内のすべてのテーブル、フィールド、および関係の完全な意味を文書化するには、「優れた」テーブル名とフィールド名では不十分であると仮定しましょう。)

多くの人がデータベースを視覚化するために UML ダイアグラムを使用していることは知っていますが、フィールドコメントを含む UML ダイアグラムを見たことはほとんどありません。.sqlただし、ファイル内でコメントを使用した経験は豊富です。このアプローチの欠点は.sql、データベース構造が時間の経過とともに変化するにつれて、ファイルを手動で最新の状態に保つ必要があることですが、そうする場合は、バージョン管理下に置くこともできます。

私が見た他のいくつかのテクニックは、データベースの構造と関係を説明する別のドキュメントと、ORM コードまたはその他のデータベースマッピングコード内の手動で維持されたコメントです。

過去にこの問題をどのように解決しましたか？どのような方法が存在し、それらに関連するさまざまな長所と短所は何ですか? 「完璧な世界」でこれをどのように解決しますか?

アップデート

他の人が指摘しているように、一般的な SQL エンジンのほとんどは実際にコメントを許可しています。これは素晴らしいことです。奇妙なことに、人々はこれらの機能をあまり使用していないようです。少なくとも、私が過去に関わったプロジェクトではそうではありません。

score 10 · Accepted Answer

MySQLでは、テーブルと行にコメントを付けることができます。PostgreSQLも同様です。他の回答から、OracleとMSSQLにもコメントがあります。

私にとっては、フィールド名、タイプ、制約を簡単に復習するためのUMLダイアグラムと、データベース関連のすべて（特別な値、フィールドコメント、アクセス）の詳細な説明を含む外部ドキュメント（TeX、ただし任意の形式）の組み合わせです。メモ、何でも-最適に機能します。

score 8 · Accepted Answer

遅いものですが、うまくいけば便利です...これは、比較的大きなデータベースを開発するときに使用したプロセスです（合計で約100のテーブルと約350のオブジェクト）

開発者は、拡張プロパティを使用してすべてのオブジェクトに詳細を追加する必要がありました。
管理者は、拡張プロパティを持たない DDL を拒否しました
サードパーティのツールを使用して、コマンドラインインターフェイスを介してビジュアルドキュメントを毎日自動的に生成しました。ApexSQL Docを使用しましたが、問題なく動作しましたが、他社の Red Gate の SQL Doc も正常に使用できました。

このプロセスにより、すべてのオブジェクトが文書化され、最新の文書が確実に作成されました。

難しかったのは、開発者に一貫して良いコメントを書いてもらうことでした ;)

score 6 · Accepted Answer

テーブルと列に付けられたコメントを使用します。SchemaSpyは、スキーマからコメントを含む HTML ドキュメントファイルを生成するための優れたツールです。

score 6 · Accepted Answer

SQL Server には、これを処理できる拡張プロパティがあります。

この記事では、SQL サーバーでそれらを設定する方法について説明します http://www.developer.com/db/article.php/3677766

MSDN リファレンス

RedGate SQL Docと組み合わせて使用すると、優れたデータディクショナリを作成できます。

score 2 · Accepted Answer

ある時点で、CREATE TABLE ステートメントを解析し、特別にフォーマットされたコメントを削除する基本的な SQL パーサーを作成しました。これらは後処理されて LaTeX ソースになり、PDF にレンダリングされました。これはJavadocに触発され、この製品のドキュメントを作成するために使用されました。その後、データディクショナリ機能がウェアハウスマネージャに組み込まれ、修正されたバージョンの LaTeX ジェネレータを使用して、ウェアハウスマネージャからデータディクショナリがレンダリングされました。

別のプロジェクトでは、Visio を使用しました。Visual Studio Enterprise Architect に付属するバージョンは、データベースをフォワードエンジニアリングします。このように生成された SQL では、テーブルと列のコメントがコメント文字列にレンダリングされており、解析が非常に簡単でした。私が作成したツールは、FrameMaker で構築された仕様書に含まれる MIF ファイルを生成しました。

Powerdesignerなどのリポジトリツールがある場合は、データモデルを維持し、入力したドキュメントを含むリポジトリレポートを取得できます。データディクショナリと機能仕様をより深く統合する必要がある場合 (ETL が複雑で、派生値の重要な計算を伴うデータウェアハウスシステムに非常に役立ちます)、メタデータを抽出し、データを統合するものを生成するユーティリティを作成できます。ディクショナリを仕様書に追加します。これにより、データディクショナリ項目と他の仕様ドキュメントとの間の相互参照や、データディクショナリの定義および関連ドキュメント (例を使用した計算方法の仕様など) をカバーするインデックスの生成も可能になります。

score 1 · Accepted Answer

プログラムにコメントするときに、データベースにコメントします。ソースコード（DDL命令を含むSQLファイル）に良い（願わくば）コメントを書くことによって。

SQLCOMMENTを使用することも可能です。それらの良い点は、それらが常にオブジェクトと一緒にあること、それらでバックアップされることなどです。悪い点は、それらがより制限されていることです（たとえば長さ）。

score 1 · Accepted Answer

私は最近、個々のテーブル.sqlファイルへのリンクを含むマークダウンドキュメントを書くようになりました (テーブルとフィールドには、多くのコメントを付けて直感的に名前を付けることができます)。

次のコマンドを使用して、個々のテーブルスキーマをバージョン管理します。

mysqldump --no-data --tab=./tables dbname

単一のテーブルのスキーマを使用すると、コメント、インデックス、一意のキーなどを表示できるため、かなり自明です (少なくともそれがアイデアです)。

マスターマークダウンドキュメントには、ユーザーテーブルなどのハイパーリンクが随所に散りばめられているため、読者はさまざまなテーブルに簡単に移動できます。

score 1 · Accepted Answer

テーブル、フィールド、およびすべての機能を一覧表示する Word 文書を作成しました。これは、すべてがどのように相互にリンク/関連しているかを示す図によって裏付けられています。これは非常に単純なドキュメントで、フィールド名 > データタイプ > 目的のテーブルをロードするだけです。

score 1 · Accepted Answer

私は、すべてのシステムオブジェクト (テーブル、列、ビュー、プロシージャとパラメーター、トリガーなど) の説明フィールドを持つFirebirdを使用しています。他のユーザーと簡単に共有できるので便利です (ドキュメントは個別ではなくデータベースと一緒です)。失うことはありません。

ほとんどの管理者。Firebird 用のツールを使用すると、これらの説明を編集できます。また、(一部またはすべての表について) 簡単に印刷できる優れた HTML または PDF レポートを作成する専用ツール (IBDesc など) がいくつかあります。

score 1 · Accepted Answer

これは非常に単純化されたアプローチですが、私は 2 つの wiki ページを使用します。1 つはデータベースの mysqldump を含み、もう 1 つはやや英語に近い形式で記述されています。

私が取り組んできたプロジェクトでは、それで十分でした (数十のテーブルレベルで)。大規模なプロジェクト (数百のテーブルなど) にどれだけうまくスケーリングできるかはわかりませんが、これまでのところうまくいっています。

score 0 · Accepted Answer

Rational Software Architect を使用しているため、そのデータ検出機能を使用してデータベースを文書化し、そこから注釈を付けています。

score 0 · Accepted Answer

Oracle では、テーブルにコメントを付けることができ、それをデータディクショナリに格納します。

ただし、テーブル、列、インデックスのすべてのコメントを非常に古いバージョンの ERWin に保存しています。これは信頼できるマスターソースであり、テーブルなどを作成するための DDL を生成します。そこから、Word ドキュメントまたは PDF に抽出できます。

sql - データベース構造をどのように文書化しますか?

12 に答える 12

Related

Reference