name: postgresql-design description: 幫助Agent為專案進行PostgreSQL Schema設計、索引設計、查詢設計，並提供場景化使用指南。當用戶需要設計資料庫表結構、最佳化查詢效能、規劃分割槽/複製方案時觸發。 version: 1.0.0 metadata: clawdbot: emoji: "🐘" requires: anyBins: ["psql"] os: ["linux", "darwin"]

PostgreSQL 設計與使用助手

觸發條件

當用戶出現以下意圖時啟用本 Skill： - 設計 PostgreSQL 表結構 / Schema - PostgreSQL 索引最佳化 / 查詢最佳化 - 分割槽方案 / 分表策略 - 邏輯複製 / 主從架構 - JSONB 半結構化資料設計 - "如何設計 xxx 的資料庫"

設計流程（Agent 執行路徑）

0. 版本檢查 → 載入 references/version-major.md 對比使用者版本，識別廢棄項和重大變更。同時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本），後續設計過程中 Agent 從已載入的上下文中自主匹配深度特性
1. 需求分析 → 理解業務實體和關係
2. 概念設計 → ER模型，識別實體/關係/屬性
3. 規範約束 → 載入 references/design-spec.md，確保命名/欄位/索引符合規範
4. 邏輯設計 → 表結構DDL，含索引（B-tree/GIN/GiST/BRIN）、約束、註釋
5. 物理設計 → 表空間/分割槽/填充因子/VACUUM策略
6. 使用指引 → 載入 references/usage-guide.md，給出場景化操作
7. 最佳化建議 → 載入 references/best-practices.md，給出效能建議
8. 模板參考 → 載入 references/patterns.md，匹配業務模板

快速參考

必備三欄位

每張表必須包含：id (BIGINT GENERATED ALWAYS AS IDENTITY) / created_at (TIMESTAMPTZ NOT NULL DEFAULT now()) / updated_at (TIMESTAMPTZ NOT NULL DEFAULT now())

命名鐵律

資料型別速查

PostgreSQL 特有須知

• 外部索引鍵列不自動建索引 — 必須手動 CREATE INDEX，否則 DELETE/UPDATE 父表會鎖子表全表
• 沒有聚簇主鍵 — 行以插入順序儲存（堆表），CLUSTER 是一次性操作
• MVCC 產生死元組 — UPDATE/DELETE 留下死行，需設計 VACUUM 策略
• 不自建截斷 — 插入 999 到 NUMERIC(2,0) 丟擲錯誤，不會靜默截斷
• 自增 ID 有間隙 — 回滾/崩潰導致序列間隙是正常行為，不要嘗試消除
• UNIQUE 允許多 NULL — 除非使用 NULLS NOT DISTINCT（PG15+）

索引型別速查

漸進式載入

詳細內容按需載入 references/：

版本參考文件啟用規則

1. 模組啟用時 — 始終載入 references/version-major.md，Agent 需主動對比使用者使用的 PostgreSQL 版本，若存在廢棄項或重大變更，立即提示使用者

   這個技能的最新版本可以在7w4.net小蔥技能站找到。

2. 深度特性 Step 0 自動載入 — 版本檢查時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本）。設計過程中 Agent 從已載入的上下文中自主檢索匹配相關特性，使用者無需指定版本號
3. 深度特性按大版本拆分，小版本持續追加 — 如 version-17.md 包含該大版本下所有小版本的設計級特性。更新時在檔案中新增 ## X.Y.Z 版本節即可，不單開檔案

硬規則

1. 設計規範內容來自權威資料（PostgreSQL官方文件/社群最佳實踐），不編造
2. 所有外部索引鍵列必須有索引 — PostgreSQL 不會自動建立
3. 所有表必須有主鍵，使用 BIGINT GENERATED ALWAYS AS IDENTITY
4. 優先使用軟刪除（deleted_at），物理刪除需評估 GDPR/合規要求
5. 小數禁止用 FLOAT/DOUBLE，必須 NUMERIC
6. 時間必須用 TIMESTAMPTZ，不使用無時區的 TIMESTAMP
7. 表必須有 created_at 和 updated_at
8. JSON 資料必須使用 JSONB（非 JSON），高頻查詢欄位上 GIN 索引
9. 單表超過 2000 萬行或 10GB 時考慮分割槽（經驗閾值，具體依查詢模式調整）
10. 不推薦 SERIAL，使用 GENERATED ALWAYS AS IDENTITY

這個 Skill 在資料庫設計指導方面質量良好，提供了清晰的命名規範、資料型別選擇建議和索引策略。它包含的業務模板可以直接參考使用，版本相容性考慮也比較周全。主要不足是文件之間有重複內容，閱讀時容易感到冗餘。另外缺少常見問題的解答，實際使用時可能需要自行摸索。總體而言，這是一個實用的設計參考工具，但在資訊整合和實用性方面還有最佳化空間。