Supabase Postgres Best Practices

Supabase Postgres Best Practices 是什么

Supabase Postgres Best Practices 是 Supabase 官方维护、但适用于任意 PostgreSQL 环境的规则集。它要求在创建或修改表、列、迁移、RLS、索引、触发器、函数、队列、定时任务、向量检索和数据导入前加载，也用于分析慢查询、高 CPU、连接耗尽、锁、膨胀和跨租户数据泄露。

适用场景与选择边界

适合数据库设计、SQL 编写、性能优化、安全审查与生产故障分析，并不限于 Supabase 托管实例。它不是一个自动执行所有 SQL 的迁移器，也不能替代备份、容量规划和人工数据治理；每条规则仍需结合版本、负载和业务一致性要求。

核心能力与工作机制

规则按查询性能、连接管理、安全与 RLS、Schema 设计、并发锁、数据访问、监控诊断和高级功能分为八类，并按 CRITICAL 到 LOW 排序。每条规则包含原理、错误与正确 SQL、执行计划分析及具体指标，方便代理生成或审查可验证的建议。

实际工作流

先判断任务属于哪一类并加载对应规则，而不是一次塞入全部参考。对变更任务，检查 schema、约束、索引、RLS 与迁移方式，再在隔离环境运行 SQL 和测试；对性能故障，先收集 EXPLAIN、连接、锁与指标，建立基线后只修改一个主要变量并复测。

输入、输出与交付物

输入包括 PostgreSQL 版本、schema、查询、执行计划、数据量、并发模型、RLS 策略和监控指标。输出可以是经过解释的 SQL、索引或策略建议、迁移和测试方案，以及前后指标；不能只给“加索引”或“扩大连接池”这类脱离证据的结论。

依赖、账号与权限

需要访问 schema 与 SQL，诊断时可能需要 EXPLAIN、系统视图和监控权限，实际修改则需要受控 DDL 或策略权限。高权限凭据应与应用账号分离；生产数据、查询参数和策略定义可能含敏感信息，分享时需脱敏。

限制与安全风险

错误索引会增加写放大，过大的连接池可能加剧耗尽，RLS 漏洞会造成越权，长事务和不当锁会阻塞生产。EXPLAIN ANALYZE 可能实际执行语句，针对写操作要谨慎。所有结构与策略变更必须有迁移、测试、观察窗口和回退。

适合谁使用

适合 PostgreSQL 开发者、Supabase 用户、后端与数据平台工程师，以及负责 RLS 多租户安全和性能的团队。初学者可按优先级从查询、连接和安全三类开始，高级用户可深入 pgvector、pg_cron、pgmq 与恢复导入。

上手与验收建议

选一条真实慢查询或一次小 schema 变更做试点，收集当前执行计划、耗时、返回行和索引。应用规则后在相同数据规模复测，并检查写入、锁和 RLS 回归。上线时使用可回退迁移，持续观察延迟、连接、CPU 和错误率。

来源、版本与许可

依据 supabase/agent-skills 固定提交中的完整 Supabase Postgres Best Practices、skills.sh 详情与 MIT 许可证整理。

常见问题

1. 这个 Skill 只能用于 Supabase 吗？

不是。官方描述明确说明规则适用于运行在任何环境的 PostgreSQL；Supabase 负责维护内容，但查询、连接、Schema、锁和监控原则可用于自托管或其他云平台。

2. 为什么改一个字段也要加载这些规则？

单列变更仍可能影响类型、默认值、锁、回填、索引、RLS 和兼容性。规则要求数据库内任何结构或 SQL 变化都先检查相应类别，避免把小改动误判成无风险。

3. 规则的优先级如何安排？

查询性能、连接管理和安全 RLS 属于 CRITICAL，Schema 设计为 HIGH，锁与并发为 MEDIUM-HIGH；数据访问、监控和高级功能随后。应先解决高影响问题。

4. 看到慢查询是否应该立即加索引？

不应。先获取执行计划、实际行数、选择性和调用频率，判断瓶颈是否来自扫描、连接、锁或错误查询形状。索引还会增加写入成本，必须前后测量。

5. RLS 策略如何验证不会串租户？

除审查策略 SQL 外，要使用不同角色和多个租户数据编写正向与反向测试，确认允许的行可见、其他租户不可见，并检查绕过 RLS 的高权限路径。

6. 连接耗尽只需增加池大小吗？

不一定。过大的连接池会把压力推给数据库。应同时检查并发、事务时长、空闲连接、Serverless 连接模式和池化层，再按数据库容量设置总连接预算。

7. EXPLAIN ANALYZE 有什么风险？

它会实际执行查询；对写语句或昂贵查询可能改变数据或加重生产负载。应在副本、事务或低风险环境使用，并先确认语句性质与观察窗口。

8. 优化完成后应该观察哪些指标？

至少比较查询延迟、执行计划、扫描与返回行、CPU、连接、锁等待和错误率；涉及索引还要观察写入与存储成本，涉及 RLS 则运行权限回归测试。