postgresql-table-design

postgresql-table-design スキルの概要

このスキルでできること

postgresql-table-design スキルは、汎用的な SQL の助言ではなく、PostgreSQL 固有のルールに沿って PostgreSQL スキーマの設計やレビューを行うためのものです。特に、正しさと長期的な性能に大きく効きやすい判断、つまり主キー、正規化、NULL 許容、デフォルト値、データ型、外部キー、インデックス、そして PostgreSQL 特有の落とし穴に重点を置いています。

どんな人に向いているか

このスキルは、新しいテーブルを作るとき、既存スキーマを見直すとき、あるいはプロダクト要件を PostgreSQL 前提の設計に落とし込みたいときに、実践的な postgresql-table-design guide を求める開発者、データエンジニア、データベースエンジニアに最適です。

実際に解決したい仕事

多くのユーザーが必要としているのは、理論の講義ではありません。粗いドメインモデルから、PostgreSQL らしい書き方で本番投入しやすいテーブル、制約、インデックスへ落とし込んでくれるエージェントです。このスキルが役立つのはまさにそこです。外部キーに対するインデックス漏れ、UUID の使いすぎ、弱いデータ型の選択、早すぎる非正規化といった、避けられるミスを減らせます。

汎用スキーマ用プロンプトと何が違うのか

最大の違いは、PostgreSQL に特化した姿勢が明確なことです。元のガイダンスでは、次の方針がはっきり打ち出されています。

• まず正規化し、非正規化は必要性を測定できてから行う
• デフォルトの主キーは BIGINT GENERATED ALWAYS AS IDENTITY
• 一般的なケースでは TIMESTAMPTZ、NUMERIC、TEXT、BIGINT を優先する
• 外部キー列には明示的にインデックスを張る
• クォートしない識別子は小文字になることや、NULL を含む列での UNIQUE など、PostgreSQL の挙動を前提に考える

向いているケース / 向いていないケース

実践的な postgresql-table-design for Database Engineering ワークフローが欲しいなら、このスキルは有力です。OLTP 系アプリのスキーマ、リレーショナルなデータモデリング、既存スキーマのレビューには特に向いています。一方で、主な課題が ETL オーケストレーション、分析モデリング、あるいはテーブル設計と関係の薄い運用 DBA 業務なら適性は下がります。

postgresql-table-design スキルの使い方

postgresql-table-design の導入時に知っておくこと

このスキルは wshobson/agents の plugins/database-design/skills/postgresql にあります。利用しているエージェント基盤が GitHub ホストのスキルに対応しているなら、リポジトリを追加して postgresql スキルを選択します。よくある導入パターンは次のとおりです。

npx skills add https://github.com/wshobson/agents --skill postgresql

別のスキルローダーを使う環境なら、次を参照先にしてください。
https://github.com/wshobson/agents/tree/main/plugins/database-design/skills/postgresql

最初に読むべきファイル

まず確認するのは次です。

• SKILL.md

このスキルは、かなり珍しいほど 1 ファイルに内容が集約されています。このスキルのパス配下には、見える範囲で補助スクリプトや参照用フォルダがないため、有用なガイダンスの大半はメインドキュメントに入っています。導入を素早く進めやすい反面、リポジトリを読む負担は小さいですが、重厚なスキルにあるような具体例は少なめだと見ておくとよいです。

スキルに渡すべき入力

このスキルは、「データベースを設計して」だけではなく、具体的なスキーマ意図を与えたときに最も力を発揮します。良い入力には通常、次の情報が含まれます。

• エンティティとその関係
• 想定される書き込み・読み取りパターン
• 一意性ルール
• NULL 許容フィールドと必須フィールドの区別
• 金額、時刻、識別子の意味づけ
• 想定スケール
• 関連行の update/delete 挙動

こうした情報がなくてもスキーマの草案は作れますが、インデックスや制約の選び方は汎用的になりやすくなります。

曖昧な要望を強いプロンプトに変える

弱いプロンプト:

• “Design PostgreSQL tables for an ecommerce app.”

より強いプロンプト:

• “Use the postgresql-table-design skill to design PostgreSQL tables for an ecommerce app. Entities: users, products, carts, orders, order_items, payments. Expected queries: list orders by user and date, fetch open cart by user, filter products by category and price. Money must be exact. All event times should preserve timezone. Users may have multiple addresses. Orders are immutable after payment except status fields. Recommend PKs, FKs, nullability, defaults, unique constraints, and indexes, then explain any denormalization you reject.”

このような強いプロンプトなら、スキルの中核ルールをうまく適用できるだけの情報量があります。

このスキルが重視しやすい最適化方針

元のガイダンスから見ると、このスキルはおおむね次の方向へ寄せてきます。

• まず正規化されたスキーマ
• UUID を使う明確な理由がない限り、代理の整数主キー
• 外部キーへの明示的なインデックス
• 金額には正確な数値型
• タイムゾーン付きタイムスタンプ
• 気の利いた一発芸より、保守しやすく堅実なデフォルト

もしシステム側で逆のトレードオフが必要なら、その点を明示的に伝えるべきです。

postgresql-table-design を実務で使う流れ

実務での postgresql-table-design usage としては、次の流れが扱いやすいです。

1. ドメインと主要クエリを説明する。
2. テーブル、カラム、制約、インデックスを含む初期スキーマを依頼する。
3. 出力を、特に PK の選び方、FK インデックス、NULL 許容、データ型の観点で確認する。
4. DDL を依頼する。
5. クエリパターンとマイグレーション上のリスクに絞った 2 回目のレビューを依頼する。

最初から SQL だけを求めるより、この順序のほうがスキルの価値を引き出しやすいです。

実運用で効くリポジトリ上の手がかり

元ファイルには明示的な “gotchas” が含まれており、ここが重要です。汎用プロンプトでは見落としやすい PostgreSQL 固有の挙動を拾ってくれるためです。特に、エージェントが次の点に触れたら注意して読む価値があります。

• クォートしない名前での小文字識別子の挙動
• UNIQUE と NULL 許容列の組み合わせ
• 精度や長さ超過時の挙動
• 外部キーには自動でインデックスが付かないこと

こうした細部は、本番での結果を実際に左右します。

出力品質を上げる強いプロンプト要素

該当するなら、次の条件を入れておくと有効です。

• “Use snake_case identifiers only.”
• “Prefer BIGINT GENERATED ALWAYS AS IDENTITY unless you justify UUID.”
• “Index all FK columns unless there is a clear exception.”
• “Use TIMESTAMPTZ for event times.”
• “Use NUMERIC for monetary values.”
• “Call out where NOT NULL and DEFAULT should be applied.”

これらはスキル本来のガイダンスと整合しているため、最初のドラフトから整った提案が出やすくなります。

早めに決めておくべき制約とトレードオフ

出力をそのまま当てにする前に、次を決めておきましょう。

• 不透明なグローバル ID が必要か、それとも単純なローカル PK でよいか
• 書き込みの単純さと読み取り速度のどちらを優先するか
• 非正規化をそもそも許容するか
• NULL 許容は「不明」「該当なし」「未収集」のどれを意味するのか
• 厳密な 10 進計算が必要か

これらの判断は、postgresql-table-design guide が、見た目だけ正しいスキーマではなく、実際にシステムに合うスキーマを出せるかどうかを直接左右します。

新規設計ではなくレビューを依頼すべき場面

このスキルはレビュー役としても有用です。すでに DDL があるなら、エージェントに次を依頼できます。

• 足りない FK インデックスの洗い出し
• 不適切な型選択の指摘
• NULL 許容とデフォルト値の点検
• 早すぎる非正規化への異議
• PostgreSQL 固有の正しさリスクの指摘

導入可否を見極めるなら、実際のコードベースでこれを試すのが最短です。

postgresql-table-design スキル FAQ

このスキルは新規スキーマ専用ですか？

いいえ。新規設計にもスキーマレビューにも使えます。成熟したシステムでは、足りないインデックス、弱い制約、疑わしい型選択を見つける用途が最も価値を出しやすいこともあります。

普通のプロンプトより何が優れていますか？

通常のプロンプトでも、それらしい SQL は出せます。ただし、PostgreSQL 固有の挙動やデフォルト方針を見落としがちです。postgresql-table-design skill を使うと、正規化、PK 選定、FK インデックス、金額と時刻の型、そして PostgreSQL でありがちな落とし穴について、エージェントの判断軸が明確になります。

postgresql-table-design は初心者にも向いていますか？

はい、基本的なリレーショナル概念を理解しているなら有用です。実践的で方針もはっきりしているため、初心者がよくあるミスを避ける助けになります。ただし、制約、インデックス、クエリパターンがどう相互作用するかを学ぶ代わりにはなりません。

これだけでマイグレーション可能な SQL を生成できますか？

必ずしもそうではありません。元の内容は、マイグレーションフレームワーク固有というより設計寄りです。DDL の下書きには使えますが、Prisma、Drizzle、Rails migrations、Django migrations、あるいは素の SQL ワークフローに合わせて調整する必要は残る場合があります。

どんなときは使わないほうがいいですか？

主な課題が次のいずれかなら、別の手段を優先したほうがよいでしょう。

• warehouse/star-schema モデリング
• ORM 固有のコード生成の細部
• テーブル設計と無関係なデータベース管理
• テーブルモデリングよりも、より広い PostgreSQL 運用が重要になる、partitioning-heavy または extension-heavy なアーキテクチャ

高度な PostgreSQL 挙動までカバーしていますか？

実務上重要な高度なポイントはいくつか扱っていますが、最大の強みは徹底したテーブル設計にあります。網羅的な PostgreSQL 内部実装の解説というより、焦点を絞った postgresql-table-design guide と捉えるのが適切です。完全なデータベースアーキテクチャフレームワークではありません。

postgresql-table-design スキルを改善する方法

エンティティ名だけでなくクエリパターンを渡す

出力を最も早く改善する方法は、重要な読み書きを具体的に渡すことです。“Users and orders” では弱すぎます。“Fetch recent orders by user, join order items, filter unpaid orders by status and created_at” のほうが、インデックスや制約の判断に直結するため、はるかに有効です。

識別子戦略を明示する

このスキルは整数の identity key を強くデフォルトとして好みます。もし公開用 ID、分散環境での生成、マージ安全性のために UUID が必要なら、最初にそう伝えてください。そうしないと、エージェントは妥当な判断として BIGINT に寄せてくる可能性があり、アーキテクチャ方針と食い違うことがあります。

どこで厳密さが必要かを伝える

金額や時刻の意味を省くと、出力が弱くなりがちです。たとえば次のように伝えます。

• “All prices require exact decimal arithmetic.”
• “Audit and event timestamps must preserve timezone.”
  これにより、スキルは NUMERIC と TIMESTAMPTZ に寄せやすくなります。これは実務上、このスキルの強みのひとつです。

スキーマの出力だけでなく、制約の理由も求める

より良いプロンプトの例は次です。

• “Design the schema, then justify each PK, FK, unique constraint, NOT NULL, and index.”

こうすることで、エージェントが本当にこのスキルの設計ロジックを使っているのか、それとも汎用的なテーブル定義を出しているだけなのかが見えやすくなります。

よくある失敗パターンを確認する

このスキルを使っていても、次の点はレビューしてください。

• FK インデックスの漏れ
• NULL 許容列の多用
• より適切な型があるのに text フィールドを使っている箇所
• 根拠の薄い非正規化
• 必要性ではなく習慣で選ばれた UUID
• NULL 許容列で破綻する一意性ルール

初稿で修正が必要になりやすいのは、たいていこのあたりです。

初稿のあとに反復する

最初の設計を受け取ったら、次のような追加質問をしてください。

• “What query paths are still under-indexed?”
• “Which columns should be NOT NULL but are not?”
• “Where would this schema create update anomalies?”
• “Which denormalizations should wait until measured performance data exists?”

最初のプロンプトを大きくするより、この 2 回目の見直しのほうが品質向上につながることが多いです。

Database Engineering チーム向けに postgresql-table-design を改善する

チーム運用なら、プロンプト入力を標準化するのが有効です。すべての依頼に次を必須化してください。

• ドメインエンティティ
• カーディナリティとライフサイクルのルール
• 重要クエリ
• 保持要件
• ID 方針
• 金額と時刻における厳密さの要件
• 想定行数の増加

こうすることで、postgresql-table-design skill の出力はレビュー担当者やプロジェクトをまたいでも安定しやすくなります。

導入前に既存 DDL のレビューで試す

このスキルを採用するか判断中なら、まず実在のスキーマレビュー 1 件で試してください。本番に近いテーブル群を渡し、PostgreSQL 固有の問題だけを指摘するよう依頼します。汎用プロンプトでは見落としていた設計上の問題を拾えるなら、その時点で導入価値はかなり明確です。