supabase-postgres-best-practices

supabase-postgres-best-practices skill 概览

supabase-postgres-best-practices skill 是 Supabase 提供的一套结构化 Postgres 优化参考，适合那些需要在 SQL、schema、索引、RLS 与连接管理上做出更靠谱判断的人，而不是满足于通用编码提示里那种泛泛建议。它尤其适合数据库工程师、后端开发者，以及在 Supabase 或原生 Postgres 系统中做 AI 辅助评审的团队——前提是你同时在意性能和正确性。

这个 skill 实际能帮你解决什么问题

当你的真实目标不是“讲讲 Postgres 是什么”，而是下面这些更具体的工作时，就该用 supabase-postgres-best-practices：

• 重写慢查询
• 选对索引形态
• 避免 N+1 和错误的分页模式
• 在不明显牺牲性能的前提下提升 RLS 安全性
• 降低锁竞争
• 判断瓶颈到底出在 query、schema 还是连接方式

它的价值在于：内容按实战规则文件组织，带有 bad-vs-good SQL 对照示例，而不是只有一些宽泛原则。

哪些用户和项目最适合用这个 skill

这个 skill 特别适合以下团队：

• 运行基于 Supabase 的应用，并希望拿到更贴近 Postgres 的具体指导
• 用 AI 审查 migration、SQL function、policy 或 schema 变更
• 希望把数据库工程中的优化模式沉淀为可重复执行的方法
• 需要关于索引、连接池、监控和查询计划的具体示例

如果你已经有现成的 schema 或 query 上下文，并希望模型基于这些信息给出扎实改进，而不是只说一句“加索引试试”，那它会特别有用。

为什么它比普通提示词更强

supabase-postgres-best-practices skill 的主要差异，不只是覆盖面更广，还包括优先级安排更合理。仓库把指导内容分成八大类，并把关键问题放在前面：query performance、connection management 和 security/RLS。配套的 references/ 文件还提供了精确的改写方式、可量化的影响以及取舍说明，这比一句“optimize my Postgres”的单行提示更能让模型产出可执行结果。

它在哪些方面覆盖得最好

supabase-postgres-best-practices skill 最强的部分包括：

• 查询索引策略，包括复合索引、covering index、partial index 与缺失索引判断
• schema 设计，如数据类型、主键、约束、分区以及 foreign key 索引
• 运维相关主题，如连接数上限、连接池、prepared statements 和 idle timeout
• 并发模式，例如 advisory locks、短事务、死锁预防与 SKIP LOCKED
• 使用 EXPLAIN ANALYZE、pg_stat_statements 以及 vacuum/analyze 做监控与诊断
• Postgres 高级特性，如 JSONB 索引和全文检索

哪些场景它并不是合适工具

它不是一整套 Postgres 管理手册、migration framework，也不是 benchmark 套件。如果你要做的是和具体环境强绑定的底层调优，比如硬件规格 sizing、WAL 配置，或复杂复制架构设计，那这个 skill 更像是面向 query 与 schema 的实战指南，而不是完整 DBA playbook。

如何使用 supabase-postgres-best-practices skill

如何安装 supabase-postgres-best-practices

如果你的 skill runner 支持从远程 GitHub 安装，可使用：

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

如果你的环境是从克隆后的仓库加载 skill，那么这个 skill 位于：

skills/supabase-postgres-best-practices

由于 SKILL.md 本身不包含安装命令，直接浏览目录的用户应以上面的仓库级安装方式为准，或遵循你本地 skill loader 的约定。

优先看这些文件

想最快进入可用状态，建议按这个顺序阅读：

1. skills/supabase-postgres-best-practices/SKILL.md
2. skills/supabase-postgres-best-practices/AGENTS.md
3. skills/supabase-postgres-best-practices/references/_sections.md
4. 与你当前问题最匹配的 references/*.md 文件

README.md 主要面向贡献者。如果你想扩展或校验这个 skill，它有帮助；但对第一次上手来说，优先级没那么高。

先从类别切入，不要一上来就读整个仓库

想高效使用 supabase-postgres-best-practices skill，最好的办法是先把问题映射到仓库前缀分类：

• query-：慢 SQL 与索引问题
• conn-：serverless 或高并发连接问题
• security-：权限与 RLS
• schema-：表和列设计
• lock-：锁竞争与队列 worker
• data-：批处理、分页、upsert 和 N+1
• monitor-：诊断与监控
• advanced-：JSONB 和全文检索

这样能明显减少 prompt drift，更快把模型拉进正确的解题路径。

什么样的输入更容易得到好结果

supabase-postgres-best-practices usage 的输出质量，很大程度取决于你给的信息是否具体。建议至少提供：

• 当前 SQL query 或 migration
• 相关表定义
• 行数或大致数据规模
• 现有索引
• 慢的表现，例如延迟、CPU、锁、连接耗尽
• 是否使用 Supabase 特性，如 RLS 或 pooled connections
• 任何正确性约束，比如“必须保留 cursor 顺序”或“policy 必须保持 tenant-safe”

如果缺少这些信息，模型通常仍会给出大方向正确的建议，但深度和命中率会明显不足。

把模糊目标改写成高质量提示

弱提示：

Optimize this Postgres query.

更好的提示：

Use the supabase-postgres-best-practices skill to review this query for index use, data access pattern issues, and RLS impact. Explain likely bottlenecks, propose rewritten SQL, recommend exact indexes, and note tradeoffs. Context: table sizes, existing indexes, and EXPLAIN ANALYZE are below.

最佳提示结构通常包括：

• objective
• current SQL/schema/policy
• workload shape
• constraints
• desired output format

这种结构和参考文件讲解“如何做改写”的方式非常契合。

用于查询优化的示例提示

你可以这样写：

Apply supabase-postgres-best-practices to this endpoint query. Check for missing composite or partial indexes, N+1 patterns, unnecessary scans, and pagination problems. If you suggest an index, explain why the predicate and sort order fit it. If EXPLAIN ANALYZE would change your confidence, say exactly what to verify.

这比直接问“best practices 是什么”更有效，因为它要求模型做判断，而不是泛泛总结。

用于 schema 和 RLS 审查的示例提示

做 schema 或 policy 审查时，可以试试：

Use the supabase-postgres-best-practices skill to review this migration and RLS policy set. Focus on foreign-key indexing, data types, constraints, lowercase identifiers, privilege boundaries, and whether the RLS predicates will scale on large tables. Return changes in priority order with SQL examples.

这个提示能把模型直接引到仓库里最有价值的参考区域。

按任务选择最佳仓库阅读路径

可以把下面这些文件路径当作快捷入口：

• 慢查询：references/query-missing-indexes.md, references/query-composite-indexes.md, references/query-covering-indexes.md
• soft-delete 或带过滤条件的工作负载：references/query-partial-indexes.md
• API 过度拉取或重复请求：references/data-n-plus-one.md, references/data-batch-inserts.md
• 分页问题：references/data-pagination.md
• worker 队列或锁竞争：references/lock-skip-locked.md, references/lock-short-transactions.md
• Supabase auth 与 policy 性能：references/security-rls-basics.md, references/security-rls-performance.md
• 排查性能变慢：references/monitor-explain-analyze.md, references/monitor-pg-stat-statements.md

这是从 supabase-postgres-best-practices for Database Engineering 中最快榨出实用价值的方式。

在真实项目中推荐的工作流

一个比较稳妥的使用流程是：

1. 先确定问题类别
2. 只加载对应的参考文件
3. 让模型给出按优先级排序的修复列表
4. 再要求它提供 SQL 改写和索引 DDL
5. 用 EXPLAIN ANALYZE 或真实 workload 数据验证
6. 先迭代最关键的一两项改动，而不是同时追所有可能的优化点

这个 skill 最擅长扮演“聚焦型评审者”，而不是发散式 brainstorming 助手。

会明显影响输出质量的实用技巧

下面这些使用细节，往往会直接拉开结果差距：

• 把现有索引贴出来，避免模型重复建议已经存在的索引
• 提供实际谓词和 ORDER BY 子句，让索引建议更贴合真实访问模式
• 告诉模型写入是否很重，因为这会影响索引方案的取舍
• 做 RLS 评审时，直接给出真实 policy 文本，否则性能建议大概率会停留在泛泛层面
• 明确要求“按优先级排序”，这样关键问题会先于可选清理项出现

supabase-postgres-best-practices skill 常见问题

supabase-postgres-best-practices 只适用于 Supabase 用户吗？

不是。虽然这个 skill 由 Supabase 维护，但其中大部分内容都是标准的 Postgres 工程实践。即使你使用的是原生 Postgres，它依然有价值，尤其是在 query planning、索引、锁、JSONB 和全文检索这些主题上。

这个 skill 适合新手吗？

它可以帮助有主动学习意愿的新手，但定位并不是“新手优先”。示例本身足够具体清晰，但很多建议默认你能看懂 SQL、理解索引，并知道如何验证执行计划。如果你刚接触 Postgres，最好结合真实 schema 使用，并同时要求模型用更通俗的语言解释每个修复项。

它相比通用 SQL 提示词，强在哪里？

supabase-postgres-best-practices guide 给模型提供了一套经过筛选的反模式、修正后 SQL、影响说明和按主题拆分的参考资料。相比普通泛化提示，它通常能产出更可落地的答案，尤其是在 partial index、RLS 性能、连接上限和锁模式这些问题上。

什么情况下不该用 supabase-postgres-best-practices？

不要指望它替代生产环境 benchmark、DBA 级基础设施调优，或特定云厂商托管服务的运维指导。如果你没有提供 schema、query 或执行计划细节，它也无法正确推断你的真实 workload。

它能做性能排查，而不只是生成代码吗？

可以。监控相关参考文件覆盖了 EXPLAIN ANALYZE、pg_stat_statements 以及 vacuum/analyze，所以这个 skill 不仅能辅助改写 SQL，也能辅助定位问题。无论你是在写 SQL 之前做设计审查，还是在发现变慢之后做诊断，它都能派上用场。

它能审查 migration 和 pull request 吗？

可以，而且这是它最值得使用的场景之一。它能检查 migration SQL、schema diff、policy 变更和 query 代码中的潜在性能或安全问题，并给出更符合 Postgres 习惯的替代方案。

如何改进 supabase-postgres-best-practices skill 的使用效果

给这个 skill 提供它真正需要的证据

想提升 supabase-postgres-best-practices 输出质量，最快的方法就是补充具体证据：

• EXPLAIN ANALYZE
• table schemas
• index definitions
• row counts
• query frequency
• read/write ratio
• policy definitions

这个 skill 的参考材料本身已经很强，但如果你的谓词条件不清楚，它依然很难在 composite index 和 partial index 之间做出靠谱选择。

要求“排序后的修复建议”，不要让它一次性倾倒建议清单

一个更强的提示写法是：

Apply supabase-postgres-best-practices and return the top 3 changes by expected impact, with exact SQL and verification steps.

这通常比“把所有问题都 review 一遍”效果更好，因为仓库本身就是按影响大小和类别优先级组织的。

强制模型给出带取舍意识的建议

你可以明确要求模型说明：

• 预期读性能收益
• 写入开销
• 存储成本
• migration 风险
• 运维层面的注意事项

这在额外索引、分区、covering index、JSONB 索引和 prepared statements 等场景里尤其重要。

需要警惕的常见失败模式

低质量输出通常会有这些表现：

• 没检查过滤条件和排序模式就直接建议索引
• 过早推荐分区
• 只讨论 RLS 正确性，不讨论 RLS 性能
• 给出连接池建议，却没考虑你的部署模型
• 改写 SQL 时没说明应如何验证执行计划是否真的改变

遇到这些问题时，最有效的做法是收窄任务范围，并明确指向对应的参考文件。

在提示词里直接写出参考文件名

如果你想让结果更精准，可以直接把文档路径写进提示，例如：

Use references/query-partial-indexes.md and references/query-composite-indexes.md to decide which index strategy fits this workload.

或者：

Apply the guidance from references/security-rls-performance.md to these policies and explain any index support they need.

由于这个 repo 是模块化结构，按文件定向提示，往往比抽象地调用整个 skill 更有效。

拿到第一轮答案后，用验证型追问继续迭代

收到第一轮结果后，可以继续追问：

• “Which recommendation has the best impact-to-risk ratio?”
• “Show the exact EXPLAIN differences I should expect.”
• “Revise the index recommendation for a write-heavy workload.”
• “Rewrite this for cursor pagination instead of offset pagination.”
• “Check whether the RLS predicate can use an index.”

很多时候，正是在这第二轮追问里，supabase-postgres-best-practices install 和使用投入才真正开始体现价值。

为 Database Engineering 团队提升输出质量

如果是团队协作场景，建议把提示模板标准化，围绕评审时真正需要的字段来设计：

• affected tables
• current and proposed SQL
• workload volume
• latency target
• existing indexes
• RLS yes/no
• deployment model
• acceptable migration risk

这样就能把 supabase-postgres-best-practices for Database Engineering 从一次性的辅助工具，变成可重复执行的评审流程。

如果你打算自己扩展这个 skill

如果你要在内部扩展，或向上游仓库贡献内容，建议遵循 repo 在 references/_template.md 和 references/_contributing.md 里的写法：先展示错误模式，再给出修正后的 SQL，并补上可量化的影响说明。正是这种结构，让这个 skill 对 agent 特别实用。