CloudBase PostgreSQL Best Practices（CloudBase PostgreSQL 最佳实践）是一个把可运行的 CloudBase PG 实现转化为可审查访问设计的技能。它的核心目标是：在代码被视为完成之前，让查询路径、索引、行授权和上线容量都变得明确。
用途 当功能需要新增或变更访问模式、应用代码存在重复/串行/高频 PG 查询、SQL 查询/RPC/接口/轮询路径变慢，或者高流量上线需要数据库就绪性检查时，使用本技能。
它不适用于：PG 环境搭建、app.rdb() 语法、迁移、GRANT 或基础 RLS 正确性（应使用 ../postgresql-development-cloudbase/SKILL.md）；登录提供方或 UI 实现（应使用对应的 auth 技能）；已确认的 NoSQL 集合工作（应使用文档数据库技能）；平台告警诊断或慢日志收集（应使用 ../ops-inspector/SKILL.md）。
兄弟技能说明 同级 CloudBase 技能与本技能一起发布，应使用本地相对路径引用，例如 ../postgresql-development-cloudbase/SKILL.md。如果当前环境中缺少被引用的兄弟技能文件，应请用户安装完整的 CloudBase 插件（或缺失的技能）。不要将远程技能或协议 markdown 通过 HTTP 抓取进智能体上下文。
工作流
- 盘点访问路径：列出每个变更的接口、任务、RPC 或 UI 流程及其读写操作，记录过滤条件、连接、排序键、预期基数和请求频率。完成标准是每条变更路径都有具体查询清单；未知量或峰值并发标记为用户假设。
- 设计模式、索引与行授权：从查询清单推导列和索引。每个频繁的过滤、连接和稳定排序路径都必须有明确的索引决策。对用户自有行，用角色作为策略门控、身份作为行谓词，例如：
CREATE POLICY orders_select_own ON public.orders FOR SELECT TO authenticated USING ((SELECT auth.uid()) = owner_id);
通过 ../postgresql-development-cloudbase/SKILL.md 定义的版本化 applyMigration 工作流应用模式 DDL，以保持 Git、开发和生产可复现；代价是实验需要新的迁移版本而非临时修改模式。 3. 实现有界数据库访问：批量处理相关键、合并重复读取、并发执行独立查询。每个结果都要通过过滤加 .limit()/.range() 限制，或通过实现键集分页的 RPC 限制。例如：
const userIds = [...new Set(rows.map((row) => row.user_id))]; const { data: profiles, error } = await db .from("profiles") .select("id, display_name") .in("id", userIds);
if (error) throw error;
将请求日志、追踪和高流量分析发送到平台日志服务或专用分析存储；PG 仅保留参与业务查询和约束的事务数据。完成标准是：变更代码中没有在逐项循环内进行数据库调用、没有同一请求中重复读取同一行、没有无界热路径查询。 4. 在流量显著时检查上线容量：对于活动、排行榜、轮询接口等突发路径，使用 queryEnv(action="info", envId=...) 检查目标环境，报告观察到的 PG 分配、预期峰值负载和未解决的容量风险。CloudBase 当前要求显式容量规划，不得将自动扩缩容表述为有保证。
路由参考
- 重复调用、串行查询、轮询、分页或日志表：references/access-patterns.md
- 缺失索引、慢 SQL/RPC 或查询计划审查：references/indexes-and-explain.md
- 新模式、租户隔离或 RLS 性能：references/schema-and-rls.md
- 活动上线或数据库规模评估：references/capacity-and-connections.md 只加载当前分支所需的参考文件。
最低自检清单
- 每条变更的访问路径都已说明。
- 每个频繁的过滤、连接和稳定排序都有索引决策。
- 数据库往返次数与结果基数无关地保持有界。
- RLS 将角色门控（TO）与行授权（auth.uid()）分离。
- 模式变更使用规范迁移工作流。
- 容量声明基于观察到的分配和已说明的流量假设。