planetscale-readonly-inventory

只读清单

目的

在不做任何更改的情况下，构建一份有证据支持的 PlanetScale 数据库清单。

允许的操作

默认允许：

• 列出组织、数据库、分支、键空间、区域和大小。
• 读取分支元数据。
• 读取 webhook 配置。
• 读取架构建议。
• 通过 MCP 或 API 读取 Query Insights、异常和查询模式。
• 读取流量预算和规则。
• 读取 Postgres 角色和非机密角色元数据。
• 读取备份计划和恢复元数据。
• 读取分支架构。
• 使用 Connections CLI 视图检查实时连接/会话元数据。
• 检查代码库文件，了解框架、ORM、迁移、SQL 标记和连接配置。
• 检查 Terraform 或其他基础设施即代码定义中的 PlanetScale 角色、备份、备份策略、Postgres 参数和受支持的扩展。

未经明确批准，不允许：

• 任何创建、更新、删除、启用、禁用、重置、部署、恢复、提升、强制执行或应用操作。
• 任何 SQL 修改操作。
• 任何会生成新凭据的命令，除非操作人员明确要求处理凭据。

接口与文档依据

所有命令和端点都应以官方文档为依据，不要猜测。PlanetScale 提供了适合 Agent 读取的文档：

• 文档索引：https://planetscale.com/docs/llms.txt
• 任意文档页面的 Markdown 版本：在其 URL 后追加 .md
• API 参考：https://planetscale.com/docs/openapi.yaml（OpenAPI 3.0）

调用端点前，请先在 API 参考中验证其路径。未经验证的路径返回 404，说明路径错误，而非发现问题；不要将其记录为平台状态，也不要据此断定“未配置”。

已验证的接口说明（命令失败时，请重新对照文档确认）：

• pscale database show <database> --org <org> — 组织是一个标志参数，而非位置参数。
• pscale api <path> 接受相对于组织的路径，例如 organizations/{org}/databases/{db}/branches/{branch} — 没有 get 子命令，也没有 /v1/ 前缀。请使用 -Q key=value 标志传递查询参数；将 ?/& 嵌入路径会导致 shell 通配符展开问题。
• pscale webhook list <database> --org <org> — 数据库是位置参数。pscale backup list <database> <branch> 必须指定分支。
• pscale branch connections top <database> <branch> — 通过预留的管理连接，可实时只读查看 Postgres 和 Vitess 的会话清单。除非操作员明确批准该操作，否则不要取消查询或终止连接。
• Query Insights 是公共 API。实时查询遥测： .../branches/{branch}/insights（按模式统计；支持 from/to/period、q、sort、dir、tablet_type、type、fields 和分页）。同一分支路径下的相关端点包括：insights/errors、insights/anomalies、insights/tags、insights/tags/summaries、insights/{fingerprint}（单次执行）、insights/{fingerprint}/summary 和 insights/{fingerprint}/traffic/budgets。query-patterns 路径返回的是生成的报告元数据，而非实时模式。
• 流量预算：.../branches/{branch}/traffic/budgets。CLI 没有 pscale traffic-control budget list；请使用 API 获取清单。
• Postgres 角色：通过 .../branches/{branch}/roles 列出；按 ID（而非名称）获取单个角色（pscale role get <db> <branch> <role-id>）。
• IP 限制：数据库级路径为 organizations/{org}/databases/{db}/cidrs。分支级 IP 限制路径无效。
• 架构建议：数据库级路径为 .../databases/{db}/schema-recommendations（分支级路径无效）。即使响应中报告了 next_page，当前请求 page=2 仍会返回 404；请以数据库对象的 open_schema_recommendations_count 作为权威总数，将返回的页面视为样本，并在报告中说明逐项清单仅涵盖部分总数。
• PITR 状态和分支级备份策略没有已验证的读取路径；请通过 pscale backup list 和数据库级备份策略记录备份状况，并标记 PITR 为“本次运行未评估”，而不是尝试探测相关路径。
• 列表端点会分页；报告计数前，请持续跟进分页参数，直至没有更多页面（上述架构建议的情况除外）。

将访问失败（403、令牌缺少权限范围、超时）记录在供操作员查看的内部运行日志中。这些不是发现项，也不应出现在客户报告中（参见 ../planetscale-customer-report-template/SKILL.md）。

清单检查表

数据库身份信息

记录：

• 组织。
• 数据库。
• 分支。
• 引擎：Vitess 或 Postgres。
• 区域和云提供商。
• 生产/开发分支状态。
• 分支保护和安全工作流状态。
• 规模和集群形态。

分支和架构工作流

对于 Vitess，记录：

• 生产分支。
• 生产和预发布分支是否启用了安全迁移。
• 未处理的部署请求。
• 部署请求审批设置。
• 待处理的架构变更。
• 分支策略是否包含一个启用了安全迁移的预发布分支。

对于 Postgres，记录：

• 分支列表。
• 分支是从备份创建的还是空分支。
• 架构变更是手动管理、通过迁移管理，还是通过 ORM 管理。
• 是否使用单独的分支测试迁移。
• 团队是否期望使用 Vitess 风格的部署请求；如果是，请注明 Postgres 分支使用部署请求的方式与 Vitess 不同。

可观测性

记录：

• 是否可以使用 Insights。
• 是否存在查询标签。
• 出现了哪些标签。
• 是否存在高基数标签。
• 是否启用了完整／原始查询收集。
• 活跃异常。
• 延迟高、读取行数多、错误率高或执行次数多的查询模式。
• 在所用的 Insights 界面中，如果能查看，则记录 Postgres CPU 密集型查询模式和 Vitess vindex 使用数据。
• 注释或标签中是否能看到应用部署标识符。

建议

记录：

• 尚未处理的架构建议。
• 建议类型。
• 受影响的表／查询。
• 建议的 DDL 或操作。
• 是否存在可安全评估该建议的分支／部署工作流。
• 是否可通过应用代码、ORM 迁移或数据库 DDL 实施该建议。

Webhook 和自动化

记录：

• 已配置的 Webhook。
• 已订阅的事件。
• 启用状态。
• 最近一次投递成功或失败的情况。
• 目标类别：Slack、PagerDuty、内部自动化、CI、Agent 队列、未知。
• 是否记录或实现了 Webhook 签名验证。
• Webhook 处理是否具有幂等性且为异步处理。

Postgres 流量控制

仅针对 Postgres，记录：

• 现有的预算和规则。
• 预算模式：关闭、警告、强制执行。
• 限制：速率、容量、突发、并发、警告阈值。
• 按指纹、keyspace、查询类型或标签设置的规则。
• 规则是否关联有意义的 SQLCommenter 标签。
• 是否有任何生产预算处于强制执行模式。

Postgres 安全性

仅针对 Postgres，记录：

• 应用角色的使用情况。
• 应用是否使用默认角色。
• 应用角色是否遵循最小权限原则。
• 是否为应用角色启用了 pg_strict。
• 适用的工作负载是否使用 PgBouncer。
• 活跃事件期间，实时连接是否显示阻塞、事务中空闲的会话或连接饱和。
• 是否配置了私有连接和 IP 限制。
• 备份保留时间和 PITR 是否符合客户的恢复预期。

Vitess 安全性

仅针对 Vitess，记录：

• 安全迁移状态。
• 部署请求工作流。
• 是否要求管理员审批。
• 是否使用门控部署。
• 是否支持架构回滚。
• 分支和 keyspace 拓扑。
• 分片／vschema 状态。
• 分片查询模式是否使用相关 vindex。
• 备份和恢复准备情况。

证据格式

对于每项发现，都需提供证据：

• 来源：MCP、CLI、API、仪表板观察、只读 SQL、代码库文件。
• 使用的路径或命令。
• 时间戳。
• 原始值或简要摘录。
• 置信度：高、中、低。

输出

返回：

• 清单表。
• 缺失证据表。
• 风险标记。
• 建议接下来运行的技能。

最后以以下内容结尾：

“未应用任何更改。”