mcpField
D
dbml-database-docs

dbml-database-docs

github.com/aircuryデータ・データベース5108 回インストール2 日前に更新
リポジトリ

dbml-database-docs について

dbml-database-docsは、DBMLでデータベース構造のドキュメントを管理するスキルです。スキーマ変更や文書化を行うリポジトリの担当者向けに、`db/schema.dbml`を正本として構造の記録と差分確認を案内します。

主な機能

  1. 01`db/schema.dbml`を正本として管理
  2. 02テーブルとカラムの記録
  3. 03キー、リレーション、インデックスの記録
  4. 04スキーマ情報源を確認する手順
  5. 05スキーマ差分の検証ガイド

活用シーン

  1. 01データベーススキーマ変更の記録
  2. 02マイグレーションとDBMLの照合
  3. 03スキーマ文書の差分解消

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aircury/ai-framework --skill dbml-database-docs

インストール後、Claude Code で/dbml-database-docsを入力して読み込まれたか確認します。

詳細

DBML データベースドキュメント

データベース構造のドキュメントを DBML で管理してください。

データベース構造やデータベースドキュメントに関わる作業では、DBML をデータベーススキーマの正式な、人にも AI にも読みやすい表現として使用してください。

正式なファイル

正式なデータベースドキュメントファイルは次のとおりです。

db/schema.dbml

リポジトリに別形式のデータベーススキーマドキュメントがあり、ユーザーからその形式を維持するよう明示的に求められていない場合は、構造スキーマのドキュメントを db/schema.dbml に移行または統合してください。

その他のドキュメントは補足説明としてのみ使用してください。DBML が適切な場合、Mermaid 図、Prisma スキーマファイル、Markdown テーブル、ORM メタデータ、説明文の要約を正式なデータベースドキュメントにしないでください。

このスキルを使用する場面

ユーザーから次のいずれかを依頼された場合に、このスキルを使用してください。

  • データベースドキュメント。
  • DB スキーマドキュメント。
  • ERD またはエンティティ関係のドキュメント。
  • テーブル、カラム、リレーション、外部キー、インデックスのドキュメント。
  • SQL、マイグレーション、Doctrine エンティティ、ORM モデル、データベースメタデータのドキュメント。
  • データベースドキュメントがマイグレーションまたは実際のスキーマと一致しているかのレビュー。
  • スキーマの不整合または DBML の不整合に関連する CI エラーの修正。
  • データベース構造の変更の追加、変更、レビュー。

構造的なデータベース変更には、次のものが含まれます。

  • 新規または変更されたマイグレーション。
  • 新規作成、名前変更、変更、削除されたテーブル。
  • 新規作成、名前変更、変更、削除されたカラム。
  • カラムの型、NULL 許容性、デフォルト値、生成値、コメントの変更。
  • 新規作成、変更、削除された主キー、外部キー、一意制約、チェック制約、インデックス、列挙型。
  • 中間テーブル、継承テーブル、監査テーブル、参照テーブルの変更。

基本ルール

構造的なデータベース変更を行う場合は、同じ作業単位で db/schema.dbml も更新してください。

マイグレーション、ORM メタデータの変更、SQL スキーマの変更に対応する DBML の更新を伴わせずに放置しないでください。ドキュメントに不整合が生じ、今後の AI セッションが古い永続化コントラクトをもとに推論することになります。

ワークフロー

  1. リポジトリにおける既存のデータベースの信頼できる情報源を確認します。
  2. 有効な構造スキーマを特定します。
  3. 現在のスキーマコントラクトを反映した db/schema.dbml を作成または更新します。
  4. 振る舞いに関する要件は specs/features/ に保持し、DBML は永続化構造に集中させます。
  5. 利用可能な場合は、該当する検証コマンドを実行します。
  6. 不整合チェックに失敗した場合は、チェックを回避せず不一致を修正します。

スキーマの情報源として、次のものが考えられます。

  • Doctrine マイグレーション。
  • Doctrine エンティティのマッピングまたは属性。
  • SQL マイグレーションファイル。
  • ORM モデル定義。
  • データベースダンプまたはスキーマスナップショット。
  • 既存の DBML ファイル。
  • CI の不整合チェック用スクリプト。

推測よりも、生成された情報やマイグレーションに裏付けられた事実を優先してください。利用可能なファイルからスキーマを確定できない場合は、不確かな点を DBML の注記に記載するか、不足している情報源をユーザーに確認してください。

DBML の記載要件

存在する場合、または推定可能な場合は、次の内容を表現してください。

  • テーブル。
  • カラム。
  • 可能な限り、データベースで実際に使われている型名によるカラム型。
  • not null 制約。
  • 主キー。
  • 外部キーとリレーションのカーディナリティ。
  • 一意制約。
  • 複合インデックスや一意性を含むインデックス。
  • デフォルト値。
  • 列挙型または値の制約セット。
  • 意味のあるデータベースコメントまたは注記。
  • 中間テーブルと多対多リレーション。
  • スキーマコントラクトに含まれる監査カラムまたはタイムスタンプカラム。

名前は正確に保持してください。ドキュメント化する際に、データベースオブジェクトを新しいものに置き換えたり、名前を変更したり、正規化したり、別の意味に解釈したりしないでください。

DBML のスタイル

レビューしやすい差分を重視し、明確な DBML を使用してください。

Table users {
  id uuid [pk]
  email varchar(255) [not null, unique]
  created_at timestamp [not null]
}

Table orders {
  id uuid [pk]
  user_id uuid [not null]
  total_amount decimal(10,2) [not null]

  Indexes {
    (user_id)
  }
}

Ref: orders.user_id > users.id

永続化コントラクトの一部である説明には Note: を使用し、一般的な製品の振る舞いには使用しないでください。

Table subscriptions {
  id uuid [pk]
  status varchar(32) [not null, note: 'Allowed by application policy: active, paused, cancelled']
}

データベースがルールを強制する場合は、DBML で対応している構造として表現してください。アプリケーションが永続化に関係するルールを強制していて、DBML で直接モデル化できない場合は、簡潔な注記を追加してください。

リレーションシップのルール

リレーションシップには、明示的な Ref: 宣言を優先して使用してください。

Ref: order_items.order_id > orders.id
Ref: order_items.product_id > products.id

外部キー名、参照先のカラム、NULL 許容性に一貫性を持たせてください。任意のリレーションシップでは、外部キーのカラムを NULL 許容にしてください。必須のリレーションシップでは、[not null] を使用してください。

インデックスのルール

各テーブルの Indexes ブロックにインデックスを記述してください。

Table users {
  id uuid [pk]
  tenant_id uuid [not null]
  email varchar(255) [not null]

  Indexes {
    (tenant_id, email) [unique]
    (email)
  }
}

エンティティのフィールドから確認できないという理由で、インデックスを省略しないでください。インデックスは永続化の契約の一部であり、重要な検索や一意性に関する前提を表していることがよくあります。

差分チェック

リポジトリにこのスクリプトが含まれている場合、データベースドキュメントの差分チェックゲートとして使用してください。

./scripts/check-schema-drift.sh

可能であれば、db/schema.dbml の更新後に実行してください。失敗した場合は、失敗の内容を確認し、実際のデータベーススキーマと db/schema.dbml が一致するようにしてください。

ユーザーからリスクを説明したうえで明示的に指示された場合を除き、チェックを無効にしたり、CI を弱めたり、フックをスキップしたり、失敗を無関係なものとして扱ったりしないでください。

CI 失敗時の対応

ユーザーから CI のスキーマ差分エラーが報告された場合：

  1. CI の出力を読み、稼働中または生成されたスキーマ、マイグレーション、db/schema.dbml のどれが古いのかを特定します。
  2. 該当するマイグレーションまたはスキーマのスナップショットと db/schema.dbml を比較します。
  3. 古い側を更新します。
  4. 利用可能な場合は、./scripts/check-schema-drift.sh を再実行します。
  5. 同期を取り直したスキーマオブジェクトを要約します。

機能仕様との境界

構造的な永続化のドキュメントには db/schema.dbml を使用してください。 外部から観察できるシステムの動作には specs/features/ を使用してください。

例：

  • users.email の一意インデックスは db/schema.dbml に記述します。
  • ユーザーがメールアドレスを変更できる条件を説明するビジネスルールは specs/features/ に記述します。
  • orders.user_id から users.id への外部キーは db/schema.dbml に記述します。
  • 注文を作成するチェックアウトの動作は specs/features/ に記述します。

構造と動作の両方を変更する場合は、両方のファイルを更新してください。

完了チェックリスト

データベースドキュメントの作業を完了する前に、次の点を確認してください。

  • データベーススキーマのドキュメントが必要な場合、db/schema.dbml が存在する。
  • 変更したすべてのテーブル、カラム、外部キー、一意制約、インデックスが記述されている。
  • DBML の名前が実際のデータベース名と完全に一致している。
  • 構造的なデータベース変更と DBML の変更が一緒に含まれている。
  • 該当する場合、動作の変更が specs/features/ に反映されている。
  • スクリプトが存在し、実行可能であれば、./scripts/check-schema-drift.sh を実行した。

コメント

Markdown 対応