前言¶

用 Cursor、Claude Code 这类 AI 编程工具写后端时，生成业务代码往往还算顺手，一碰到 Postgres 就容易翻车：外键没建索引、查询全表扫描、连接池打满、RLS 只写在应用层……这些坑在本地小数据上看不出来，上线后才会以慢查询、超时、甚至数据串租户的方式暴露出来。

2026 年 1 月，Supabase 发布了面向 AI Agent 的 Postgres 最佳实践 Skill：supabase-postgres-best-practices。它把官方沉淀的规则写成 Agent Skills 标准格式，让助手在改表、写 SQL、配 RLS、排查性能时，按优先级去对照，而不是凭训练记忆“猜”一套做法。本文按官方仓库与文档核实后，介绍它是什么、怎么装、怎么用。

这是什么¶

supabase-postgres-best-practices 是 Supabase 维护的 Postgres 最佳实践 Skill（当前元数据版本为 1.1.1，MIT 许可）。定位很明确：不只给 Supabase 托管库用，也适用于“跑在任何地方的 Postgres”。

官方描述要求：在创建/修改表与列、做 schema 与迁移、写 RLS 与相关测试、加索引、写触发器与数据库函数、处理队列/定时任务（如 pg_cron、pgmq）、向量检索（pgvector）、导入数据，以及诊断慢查询、高 CPU、超时、连接耗尽、锁等待、膨胀、租户数据可见性错误等问题之前，先加载这套规则。换句话说，它覆盖性能，也覆盖 schema、安全与日常 SQL 写法。

仓库地址：https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
技能目录页：https://skills.sh/supabase/agent-skills/supabase-postgres-best-practices
官方介绍博文：https://supabase.com/blog/postgres-best-practices-for-ai-agents

核心能力：八类规则，按影响排序¶

Skill 本体是 SKILL.md，细则在 references/ 目录。每条规则通常包含：为何重要、错误示例、正确示例，以及可选的 EXPLAIN/指标说明；涉及 Supabase 时会附带平台相关备注。

按影响从高到低，八个类别如下（前缀对应规则文件名）：

当前仓库中可见的规则文件覆盖例如：缺失索引与部分索引、连接池与连接上限、RLS 基础与性能、主键/外键/数据类型、死锁与短事务、分页与批量写入、EXPLAIN ANALYZE 与 pg_stat_statements、JSONB 与全文检索等。官方博文曾概括为约 30 条可引用规则；Agent 会按任务去读对应的 references/*.md，而不是一次塞进全部上下文。

安装与启用¶

该 Skill 遵循 Agent Skills 开放格式，可在 Cursor、Claude Code、GitHub Copilot、VS Code、Gemini CLI 等支持该标准的工具中使用。官方推荐用 Vercel 的 skills CLI 安装。

只装本 Skill：

npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

skills.sh 上也给出等价写法（指向同一仓库）：

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

安装整个 supabase/agent-skills 仓库（含 supabase 与本 Skill）：

npx skills add supabase/agent-skills

默认按项目范围安装，Skill 会落在仓库里，方便同事和云端 Agent 共用；需要全局安装时可加 --global。更新已安装 Skill：

npx skills update

若使用 Claude Code，也可走插件市场：

claude plugin marketplace add supabase/agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

更完整的安装说明见官方文档：https://supabase.com/docs/guides/getting-started/ai-skills

装好后一般无需额外开关：相关任务出现时，Agent 会自动发现并加载 Skill。官方还提醒：MCP（例如 Supabase MCP）负责连库执行，本 Skill 负责“怎么做才对”；两者搭配时，助手既有操作能力，也有规则约束。

典型用法¶

装好之后，直接用自然语言即可，例如：

Optimize this Postgres query

Review my schema for performance issues

Help me add proper indexes to this table

也可以更具体地指向规则类别，比如“按 RLS 规则给多租户订单表写策略并说明测试方式”，或“检查这条迁移会不会长时间锁表”。

下面是官方博文与规则文件里同类示例的简化对照，便于理解 Agent 会参照怎样的正误写法。

1. WHERE/JOIN 列缺索引（query-missing-indexes）

不正确：大表上对未建索引列过滤，容易变成顺序扫描。

select * from orders where customer_id = 123;
-- EXPLAIN 可能显示：Seq Scan on orders ...

正确：在常用过滤列（以及外键引用侧）建索引。

create index orders_customer_id_idx on orders (customer_id);

select * from orders where customer_id = 123;
-- EXPLAIN 可能显示：Index Scan using orders_customer_id_idx ...

2. 多租户只靠应用层过滤（官方博文 RLS 示例）

不正确：仅在应用里拼 where user_id = ...，一旦绕过就暴露全表。

select * from orders where user_id = $current_user_id;
-- 若写成 select * from orders; 则可能返回全部订单

正确：在库内启用 RLS，并用策略约束可见行（Supabase Auth 场景常用 auth.uid()）：

alter table orders enable row level security;

create policy orders_user_policy on orders
  for all
  to authenticated
  using (user_id = auth.uid());

Agent 在写迁移、改 schema、做性能 review 时，会按类别去读 references/ 下的细则，再给出带正误对照的建议。

适用场景与注意点¶

适合这些情况：

• 用 AI 助手写或改 Postgres schema、迁移、索引与查询
• 配置连接池、排查连接耗尽或 serverless 下的连接问题
• 设计/审查 RLS 与权限，避免“应用层过滤看起来对了、库层却没兜住”
• 做性能 review：慢查询、锁争用、N+1、分页与批量写入
• 与 Supabase MCP 或 CLI 一起用，让“能执行”变成“按规则执行”

需要注意：

• Skill 提供的是可引用规则与示例，不能替代真实环境的 EXPLAIN ANALYZE、监控与压测结论。
• 规则按影响分级；落地时仍要结合表规模、读写比例和业务约束取舍（例如索引能加速读，也可能增加写成本）。
• 仓库里还有更偏产品面的 supabase Skill；做纯 Postgres 优化优先本 Skill，做 Auth/Storage/Edge Functions 等产品集成可配合安装 supabase。
• Supabase 会持续更新规则，生产项目建议定期执行 npx skills update。

小结¶

supabase-postgres-best-practices 把 Supabase 在托管 Postgres 中反复见到的问题，整理成 Agent 可加载的分级规则：查询与连接、RLS 与 schema、锁与数据访问模式，再到监控与高级特性。对已经在用 AI 写后端的人来说，它补的是“正确 Postgres”这一层判断，而不是又一份散落的文档链接。

官方地址：https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
安装命令：npx skills add supabase/agent-skills --skill supabase-postgres-best-practices