すべてのガイドに戻る
データベース設計··読了時間 3 分

データベースの文書化:ERDでSQLスキーマを説明する

チームがデータモデルをより速く理解できるように、ERD、SQL の例、関係のメモ、および移行のコンテキストを使用してデータベース スキーマを文書化します。

外部キーとビジネスルールを説明するメモの横にある顧客対注文の図
このガイドの内容
  1. データベースドキュメントが失敗する理由
  2. スキーマドキュメントに含めるべき内容
  3. ドキュメントブロックの例
  4. 実践的なドキュメント作成ワークフロー
  5. 参考資料と詳細な読み物

SQL の例では、別のダイアレクトが指定されていない限り PostgreSQL を使用します。短いスニペットは、参照されているテーブルがすでに存在することを前提としています。適用する前に、ターゲットデータベースで DDL を検証してください。

データベースドキュメントが失敗する理由

データベースのドキュメントは、スキーマとは別に作成されるため、古くなりがちです。最初のデザインスプリント中に誰かが図を作成し、その後6か月にわたってデータベースが変更されると、ドキュメントは知らぬ間に誤解を招くものになってしまいます。

より良いアプローチは、ドキュメントを SQL ソースの近くに保つことです。DDL から図を生成し、テーブルとリレーションシップに関する短い説明を追加し、スキーマが変更されるたびにドキュメントを更新します。

SQL スキーマ、ERD 図、リレーションシップノート、およびマイグレーションコンテキストを統合したドキュメント
優れたデータベースドキュメントは、SQL ソースと ERD および短いリレーションシップノートを組み合わせることで、ドキュメントの実用性を維持します。

スキーマドキュメントに含めるべき内容

役立つデータベースドキュメントは、開発者が機能構築や本番データのデバッグ中に実際に問いかける疑問に答えます。

  • ERD。 テーブル、主キー、外部キー、および主要なリレーションシップのパスを表示します。
  • テーブルの目的に関するメモ。 主要なテーブルがそれぞれ存在する理由と、それを所有する機能を説明してください。
  • リレーションシップのルール。 カーディナリティ、オプショナルなリレーションシップ、およびカスケードアクションを指定します。
  • 重要な制約。 一意キー、チェック、列挙値、および SQL によって強制されるビジネスルールを文書化します。
  • マイグレーションコンテキスト。 スキーマの変更を、その背景にある機能、バグ修正、または運用上の理由に関連付けてください。

ドキュメントブロックの例

軽量なドキュメントエントリは、SQL と平易な言葉によるメモを組み合わせることができます:

CREATE TABLE accounts (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL
);

CREATE TABLE invoices (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    account_id  BIGINT NOT NULL REFERENCES accounts (id),
    status      VARCHAR(30) NOT NULL DEFAULT 'draft',
    total       NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
    due_date    DATE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE invoice_payments (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    invoice_id  BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
    amount      NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
    paid_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

ドキュメントの注記には次のように記載されている場合があります:アカウントには多くの請求書があり、請求書には多くの支払い記録があり、テスト請求書が削除されると支払い行が削除されます。監査要件のある本番システムでは、カスケード削除を制限付き削除やアーカイブ記録に置き換えることができます。

実践的なドキュメント作成ワークフロー

これは、ドキュメント作成を専任の業務にすることなく、ドキュメントを有用な状態に維持するためのワークフローです。

  • SQL スキーマから始めて、次の場所で ERD を生成します Erd Go エディター.
  • 図をエクスポートするか、サインインして保存し、スキーマが公開アクセスに適している場合は読み取り専用の公開リンクを共有します。プライベートなドキュメントには画像のエクスポートを使用します。
  • auth、billing、orders、content、audit、または reporting など、重要なテーブルクラスターごとに短い段落を 1 つ追加します。
  • 移行中に更新された SQL から ERD を再生成し、変更内容がドキュメントに反映されるようにします。
  • 構文の例を以下と同期させてください: Erd Go DDL ドキュメント 将来のコントリビューターが図を再現できるようにします。

目標は完璧な百科事典を作ることではありません。目標は、人々がデータベースを迅速に理解し、読んでいる内容を信頼できるように支援する生きたマップです。

参考資料と詳細な読み物

もっと見る