PostgreSQL テーブル設計

概要

このパブリック版は https://github.com/sickn33/antigravity-awesome-skills から plugins/antigravity-awesome-skills-claude/skills/postgresql をネイティブな Omni Skills 編集形式にパッケージ化したもので、その出所を隠さずに保持しています。

オペレーターがアップストリームワークフロー、サポートファイル、およびリポジトリコンテキストを保ったまま、パブリックバリデーターとプライベート強化機能が通常のダウンストリームフローを継続する必要がある場合に使用します。

このインテークはコピーされたアップストリームファイルを保持し、metadata.json 内の external_source ブロックと ORIGIN.md をプロベナンスアンカーとして使用してレビューを行います。

PostgreSQL テーブル設計

インポートされたソースセクションのうち、パブリックな見出しにきれいにマッピングされなかったものは以下またはサポートファイルで保持されています。注目すべきインポートされたセクション: Safety、PostgreSQL "Gotchas"、Data Types、Table Types、Row-Level Security、Constraints。

このスキルをいつ使用するか

このセクションをトリガーフィルターとして使用します。オペレーターがファイルを読み込む前、コマンドを実行する前、またはプルリクエストを開く前に、起動の境界を明示する必要があります。

• PostgreSQL のスキーマを設計する
• データ型と制約を選択する
• インデックス、パーティション、または RLS ポリシーを計画する
• テーブルをスケーラビリティと保守性についてレビューする
• PostgreSQL 以外のデータベースをターゲットにしている
• スキーマ変更なしにクエリチューニングだけが必要

オペレーティングテーブル

状況	ここから開始	重要な理由
初回使用	metadata.json	コピーされたワークフローに触れる前に、external_source ブロックを通じてリポジトリ、ブランチ、コミット、およびインポートされたパスを確認
プロベナンスレビュー	ORIGIN.md	レビュアーにインポートされたソースの平文の監査証跡を提供
ワークフロー実行	SKILL.md	実行を実質的に変更するコピーされた最小のファイルから開始
サポーティングコンテキスト	SKILL.md	パッケージ全体を読み込まずに、次に関連性の高いコピーされたソースファイルを追加
ハンドオフの判断	## Related Skills	タスクが異なる方向に流れた場合、オペレーターがより強力なネイティブスキルに切り替えるのを支援

ワークフロー

このワークフローは意図的に編集的かつ操作的です。インポートされたソースをオペレーターにとって有用に保ちながら、ダウンストリーム強化フローにフィードするパブリックインテーク標準を満たしています。

1. エンティティ、アクセスパターン、スケールターゲット(行数、QPS、保持期間)を取得します。
2. 不変量を強制するデータ型と制約を選択します。
3. 実際のクエリパスのインデックスを追加し、EXPLAIN で検証します。
4. スケールまたはアクセス制御で必要な場所でパーティショニングまたは RLS を計画します。
5. マイグレーション影響をレビューし、変更を安全に適用します。
6. ユーザーの目標、インポートされたワークフローの範囲、およびこのスキルがタスクに適したルーターであるかどうかを確認します。
7. コピーされたアップストリームサポートファイルを読み込む前に、概要とプロベナンスファイルを読んでください。

インポートされたワークフロー注記

インポート: 手順

1. エンティティ、アクセスパターン、スケールターゲット(行数、QPS、保持期間)を取得します。
2. 不変量を強制するデータ型と制約を選択します。
3. 実際のクエリパスのインデックスを追加し、EXPLAIN で検証します。
4. スケールまたはアクセス制御で必要な場所でパーティショニングまたは RLS を計画します。
5. マイグレーション影響をレビューし、変更を安全に適用します。

インポート: Safety

• バックアップとロールバック計画なしに本番環境で破壊的な DDL を避けます。
• スキーマ変更を適用する前にマイグレーションとステージング検証を使用します。

例

例 1: アップストリームワークフローを直接リクエストする

Use @postgresql to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

説明: これはオペレーターがインポートされたワークフローを必要とする場合の最も安全な出発点ですが、リポジトリ全体は必要ありません。

例 2: プロベナンスに基づくレビューをリクエストする

Review @postgresql against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

説明: レビューまたはトラブルシューティング時に、出所とファイル選択の正確で監査可能な説明が必要な場合に使用します。

例 3: 実行前にコピーされたサポートファイルを絞り込む

Use @postgresql for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

説明: これにより、スキルがデフォルトでコピーされたパッケージ全体を読み込む代わりに、段階的な情報開示に合わせられます。

例 4: レビュアーパケットを構築する

Review @postgresql using the copied upstream files plus provenance, then summarize any gaps before merge.

説明: PR がヒューマンレビューを待っており、繰り返し可能な監査パケットが必要な場合に便利です。

インポートされた使用方法に関する注記

インポート: 例

Users

CREATE TABLE users (
  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX ON users (LOWER(email));
CREATE INDEX ON users (created_at);

Orders

CREATE TABLE orders (
  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  user_id BIGINT NOT NULL REFERENCES users(user_id),
  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ON orders (user_id);
CREATE INDEX ON orders (created_at);

JSONB

CREATE TABLE profiles (
  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
  attrs JSONB NOT NULL DEFAULT '{}',
  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
);
CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);

ベストプラクティス

生成されたパブリックスキルをアップストリームリポジトリの周りにレビュー可能なパッケージングレイヤーとして扱います。目的は、プロベナンスを明示的に保ちながら、実行を実質的に改善するコピーされたソース資料だけを読み込むことです。

• 参照テーブル(users、orders など)のプライマリキーを定義します。時系列/イベント/ログデータでは常に必要ではありません。使用する場合は BIGINT GENERATED ALWAYS AS IDENTITY を優先します。グローバルな一意性/不透明性が必要な場合にのみ UUID を使用してください。
• 最初に正規化(第 3 正規形まで)してデータ冗長性と更新異常を排除します。測定され、投資対効果の高い読み取りでジョインパフォーマンスが証明されている場合にのみ正規化を解除します。早すぎる正規化解除は保守の負担を作成します。
• 意味的に必要な場所のすべてで NOT NULL を追加します。一般的な値に DEFAULT を使用します。
• 実際にクエリするアクセスパスのインデックスを作成します: PK/ユニーク(自動)、FK カラム(マニュアル!)、頻繁なフィルター/ソート、ジョインキー。
• イベント時間には TIMESTAMPTZ、お金には NUMERIC、文字列には TEXT、整数値には BIGINT、浮動小数点数には DOUBLE PRECISION(または正確な 10 進演算には NUMERIC)を優先してください。
• インポートされたスキルをアップストリームリポジトリに基づいたものにしておきます。ソース資料がサポートできないステップを作成しないでください。
• ワークフローが監査可能で高速にレビューできるように、最小限の有用なサポートファイルセットを優先します。

インポートされた操作上の注記

インポート: コアルール

• 参照テーブル(users、orders など)のプライマリキーを定義します。時系列/イベント/ログデータでは常に必要ではありません。使用する場合は BIGINT GENERATED ALWAYS AS IDENTITY を優先します。グローバルな一意性/不透明性が必要な場合にのみ UUID を使用してください。
• 最初に正規化(第 3 正規形まで)してデータ冗長性と更新異常を排除します。測定され、投資対効果の高い読み取りでジョインパフォーマンスが証明されている場合にのみ正規化を解除します。早すぎる正規化解除は保守の負担を作成します。
• 意味的に必要なすべての場所でNOT NULLを追加します。一般的な値にDEFAULT を使用します。
• 実際にクエリするアクセスパスのインデックスを作成します: PK/ユニーク(自動)、FK カラム(マニュアル!)、頻繁なフィルター/ソート、ジョインキー。
• イベント時間にはTIMESTAMPTZ、お金にはNUMERIC、文字列にはTEXT、整数値にはBIGINT、浮動小数点数にはDOUBLE PRECISION(または正確な 10 進演算には NUMERIC)を優先してください。

トラブルシューティング

問題: オペレーターがインポートされたコンテキストをスキップし、一般的すぎるアンサーを提供した

症状: 結果が plugins/antigravity-awesome-skills-claude/skills/postgresql のアップストリームワークフローを無視するか、プロベナンスについて言及しないか、またはコピーされたソースファイルをまったく使用していません。 解決策: metadata.json、ORIGIN.md、および最も関連性の高いコピーされたアップストリームファイルを再度開きます。最初に external_source ブロックをチェックし、続行する前にプロベナンスを再度述べてください。

問題: インポートされたワークフローがレビュー中に不完全に感じる

症状: レビュアーは生成された SKILL.md を確認できますが、どの参照、例、またはスクリプトが現在のタスクに重要であるかをすぐに判断できません。 解決策: 採用したパスを正当化する正確なコピーされた参照、例、スクリプト、またはアセットをポイントしてください。ギャップがまだ実在する場合は、隠す代わりに PR に記録してください。

問題: タスクが別の専門分野にずれた

症状: インポートされたスキルは正しい場所で開始しますが、作業がデバッグ、アーキテクチャ、設計、セキュリティ、またはリリース調整に変わり、ネイティブスキルがより良く処理できます。 解決策: 関連スキルセクションを使用して意図的にハンドオフします。インポートされたプロベナンスを表示したままにして、次のスキルが盲目的に開始する代わりに正しいコンテキストを継承できるようにします。

関連スキル

• @00-andruia-consultant - このインポートされたスキルがコンテキストを確立した後、作業がそのネイティブ専門分野によってより良く処理される場合に使用します。
• @00-andruia-consultant-v2 - このインポートされたスキルがコンテキストを確立した後、作業がそのネイティブ専門分野によってより良く処理される場合に使用します。
• @10-andruia-skill-smith - このインポートされたスキルがコンテキストを確立した後、作業がそのネイティブ専門分野によってより良く処理される場合に使用します。
• @10-andruia-skill-smith-v2 - このインポートされたスキルがコンテキストを確立した後、作業がそのネイティブ専門分野によってより良く処理される場合に使用します。

追加リソース

このインポートされたスキルのオペレーターパケットとして、以下のサポートマトリックスとリンク付きファイルを使用します。それらは一般的なスカッフォルディングではなく、実際にコピーされたソース資料を反映する必要があります。

リソースファミリー	レビュアーに提供すること	例パス
references	アップストリームからコピーされた参照ノート、ガイド、または背景資料	references/n/a
examples	アップストリームからコピーされた完成度の高い例または再利用可能なプロンプト	examples/n/a
scripts	実行または検証を変更するアップストリームヘルパースクリプト	scripts/n/a
agents	インポートされたパッケージの一部である真のルーティングまたは委譲ノート	agents/n/a
assets	ソースパッケージからコピーされたサポートアセットまたはスキーマ	assets/n/a

インポートされた参考ノート

インポート: インデックス

• B-tree: 等値/範囲クエリのデフォルト(=、<、>、BETWEEN、ORDER BY)
• 複合: 順序は重要—インデックスは左端のプレフィックスの等値の場合に使用(WHERE a = ? AND b > ? は (a,b) のインデックスを使用しますが、WHERE b = ? は使用しません)。最も選択的/頻繁にフィルター処理される列を最初に配置します。
• カバリング: CREATE INDEX ON tbl (id) INCLUDE (name, email) - テーブルにアクセスせずにインデックスのみのスキャンのための非キー列を含めます。
• 部分: ホットサブセット(WHERE status = 'active' → CREATE INDEX ON tbl (user_id) WHERE status = 'active')。status = 'active' を含むすべてのクエリはこのインデックスを使用できます。
• 式: 計算された検索キー(CREATE INDEX ON tbl (LOWER(email)))。式は WHERE 句で正確にマッチする必要があります: WHERE LOWER(email) = 'user@example.com'。
• GIN: JSONB 包含/存在、配列(@>、?)、フルテキスト検索(@@)
• GiST: 範囲、幾何学、除外制約
• BRIN: 非常に大きく、自然に順序付けられたデータ(時系列)—最小限のストレージオーバーヘッド。行順序がディスク上のインデックス付き列と関連付けられている場合(挿入順またはクラスター後)に効果的。

インポート: PostgreSQL "Gotchas"

• 識別子: クォートなし→ 小文字。クォートされた/混合ケースの名前を避けます。慣例: テーブル/列名に snake_case を使用します。
• 一意性 + NULL: UNIQUE は複数の NULL を許可します。UNIQUE (...) NULLS NOT DISTINCT(PG15+)を使用して 1 つの NULL に制限します。
• FK インデックス: PostgreSQL は FK 列に自動的にインデックスを作成しません。それを追加してください。
• サイレント型強制なし: 長さ/精度オーバーフロー(切り詰めなし)はエラーになります。例: NUMERIC(2,0) に 999 を挿入するとエラーで失敗し、サイレント切り詰めまたは丸めを行う一部のデータベースとは異なります。
• シーケンス/ID にはギャップがある(正常です。修正しないでください)。ロールバック、クラッシュ、同時実行トランザクションは ID シーケンス(1、2、5、6...)にギャップを作成します。これは予期される動作です—ID を連続にしようとしないでください。
• ヒープストレージ: デフォルトではクラスター化された PK がない(SQL Server/MySQL InnoDB とは異なります)。CLUSTER は 1 回限りの再構成であり、その後の挿入では保持されません。ディスク上の行順序は明示的にクラスター化されない限り、挿入順です。
• MVCC: 更新/削除はデッドタプルを残し、vacuum がそれを処理します—ホットワイド行の変動を避けるように設計します。

インポート: データ型

• ID: BIGINT GENERATED ALWAYS AS IDENTITY が推奨(GENERATED BY DEFAULT も可)。マージ/フェデレーション/分散システムで使用される場合、またはオペークな ID の場合は UUID。uuidv7()(PG18 + 推奨)または gen_random_uuid()(より古い PG バージョン使用時)で生成します。
• 整数: ストレージスペースが重大でない限り BIGINT を優先します。より小さい範囲の場合は INTEGER。SMALLINT は制約がない限り避けます。
• 浮動小数点: ストレージスペースが重大でない限り REAL より DOUBLE PRECISION を優先します。正確な 10 進演算には NUMERIC を使用します。
• 文字列: TEXT を優先します。長さ制限が必要な場合は、VARCHAR(n) の代わりに CHECK (LENGTH(col) <= n) を使用します。CHAR(n) は避けます。バイナリデータには BYTEA を使用します。大文字列/バイナリ(> 2KB デフォルト閾値)は自動的に TOAST に圧縮付きで保存されます。TOAST ストレージ: PLAIN(TOAST なし)、EXTENDED(圧縮 + アウトオブライン)、EXTERNAL(アウトオブライン、圧縮なし)、MAIN(圧縮、可能であれば インライン)。デフォルト EXTENDED は通常最適です。ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy および ALTER TABLE tbl SET (toast_tuple_target = 4096) で閾値を制御します。大文字小文字を区別しない: ロケール/アクセント処理には非決定論的なコレーション使用。純粋な ASCII には LOWER(col)(列が大文字小文字を区別しない PK/FK/UNIQUE が必要でない限り優先) または CITEXT の式インデックスを使用します。
• お金: NUMERIC(p,s)(浮動小数点数は使用しない)。
• 時間: タイムスタンプには TIMESTAMPTZ、日付のみには DATE、期間には INTERVAL。TIMESTAMP(タイムゾーンなし)は避けます。トランザクション開始時間には now()、現在の壁時計時間には clock_timestamp() を使用します。
• ブール値: 3 状態の値が必要でない限り、NOT NULL 制約付きの BOOLEAN。
• 列挙型: 小さく安定したセット(例: US 州、曜日)の場合は CREATE TYPE ... AS ENUM。ビジネスロジック駆動型で進化する値(例: 注文ステータス)→ TEXT(または INT)+ CHECK またはルックアップテーブルを使用します。
• 配列: TEXT[]、INTEGER[] など。要素をクエリする順序付きリストに使用します。包含(@>、<@)および重複(&&)クエリの場合は GIN でインデックスします。アクセス: arr[1](1 インデックス)、arr[1:3](スライシング)。タグ、カテゴリに適切。リレーションに使用しないでください—ジャンクションテーブルを使用してください。リテラル構文: '{val1,val2}' または ARRAY[val1,val2]。
• 範囲型: 区間には daterange、numrange、tstzrange。重複(&&)、包含(@>)、演算子をサポートします。GiST でインデックスします。スケジューリング、バージョニング、数値範囲に適切。境界スキームを選択して一貫して使用します。デフォルトで [) (包含/除外)を優先します。
• ネットワーク型: IP アドレスには INET、ネットワーク範囲には CIDR、MAC アドレスには MACADDR。ネットワーク演算子(<<、>>、&&)をサポートします。
• 幾何学型: 2D 空間データには POINT、LINE、POLYGON、CIRCLE。GiST でインデックスします。高度な空間フィーチャーについては PostGIS を検討してください。
• テキスト検索: フルテキスト検索ドキュメントには TSVECTOR、検索クエリには TSQUERY。tsvector を GIN でインデックスします。常に言語を指定します: to_tsvector('english', col) および to_tsquery('english', 'query')。単一引数版は使用しないでください。これはインデックス式とクエリの両方に適用されます。
• ドメイン型: 再利用可能なカスタム型と検証の場合は CREATE DOMAIN email AS TEXT CHECK (VALUE ~ '^[^@]+@[^@]+$')。テーブル全体で制約を強制します。
• 複合型: 列内の構造化データの場合は CREATE TYPE address AS (street TEXT, city TEXT, zip TEXT)。(col).field 構文でアクセスします。
• JSONB: JSON よりも優先。GIN でインデックスします。オプション/半構造化属性にのみ使用します。コンテンツの元の順序を保存する必要がある場合にのみ JSON を使用してください。
• ベクトル型: 埋め込みのベクトル類似度検索には pgvector による vector 型。

以下のデータ型を使用しないでください

• timestamp(タイムゾーンなし)を使用しないでください。代わりに timestamptz を使用してください。
• char(n) または varchar(n) を使用しないでください。代わりに text を使用してください。
• money 型を使用しないでください。代わりに numeric を使用してください。
• timetz 型を使用しないでください。代わりに timestamptz を使用してください。
• timestamptz(0) または他の精度仕様を使用しないでください。代わりに timestamptz を使用してください。
• serial 型を使用しないでください。代わりに generated always as identity を使用してください。

インポート: テーブルタイプ

• 通常: デフォルト。完全に耐久性があり、ログされます。
• TEMPORARY: セッションスコープ、自動削除、ログなし。スクラッチ作業の方が高速。
• UNLOGGED: 永続的ですがクラッシュセーフではありません。書き込みは高速。キャッシュ/ステージングに適切。

インポート: 行レベルセキュリティ

ALTER TABLE tbl ENABLE ROW LEVEL SECURITY で有効化します。ポリシーを作成: CREATE POLICY user_access ON orders FOR SELECT TO app_users USING (user_id = current_user_id())。行レベルでのビルトインユーザーベースのアクセス制御。

インポート: 制約

• PK: 暗黙の UNIQUE + NOT NULL。B-tree インデックスを作成します。
• FK: ON DELETE/UPDATE アクション(CASCADE、RESTRICT、SET NULL、SET DEFAULT)を指定します。参照カラムの明示的インデックスを追加—ジョイン速度を上げ、親の削除/更新時のロック問題を防ぎます。循環 FK 依存関係の場合は DEFERRABLE INITIALLY DEFERRED を使用してトランザクション終了時に