planetscale-readonly-inventory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read-only inventory

只读盘点

Purpose

目的

Build an evidence-backed inventory of a PlanetScale database without making changes.

构建一份基于证据的PlanetScale数据库盘点，且不进行任何更改。

Allowed actions

允许的操作

Allowed by default:

List organizations, databases, branches, keyspaces, regions, and sizes.
Read branch metadata.
Read webhook configuration.
Read schema recommendations.
Read Query Insights, anomalies, and query patterns through MCP or API.
Read traffic budgets and rules.
Read Postgres roles and non-secret role metadata.
Read backup schedules and restore metadata.
Read branch schema.
Inspect live connection/session metadata with the Connections CLI view.
Inspect repository files for frameworks, ORMs, migrations, SQL tagging, and connection config.
Inspect Terraform or other infrastructure-as-code definitions for PlanetScale roles, backups, backup policies, Postgres parameters, and supported extensions.

Not allowed without explicit approval:

Any create, update, delete, enable, disable, reset, deploy, restore, promote, enforce, or apply operation.
Any SQL mutation.
Any command that emits new credentials unless the operator explicitly asked for credential work.

默认允许：

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

未经明确批准不允许：

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

Interfaces and documentation grounding

接口与文档依据

Ground every command and endpoint in the official documentation instead of guessing. PlanetScale publishes agent-readable docs:

Docs index: https://planetscale.com/docs/llms.txt
Any docs page as markdown: append
```
.md
```
to its URL
API reference: https://planetscale.com/docs/openapi.yaml (OpenAPI 3.0)

Verify an endpoint path in the API reference before calling it. A 404 from an unverified path is a wrong path, not a finding; do not record it as platform state and do not conclude "not configured" from it.

Verified interface notes (recheck against the docs when a command fails):

```
pscale database show <database> --org <org>
```
— the org is a flag, not a positional argument.
```
pscale api <path>
```
takes org-relative paths such as
```
organizations/{org}/databases/{db}/branches/{branch}
```
— there is no
```
get
```
subcommand and no
```
/v1/
```
prefix. Pass query parameters with
```
-Q key=value
```
flags; embedding
```
?
```
/
```
&
```
in the path breaks under shell globbing.

pscale webhook list <database> --org <org>

— the database is a positional argument.

pscale backup list <database> <branch>

requires the branch.

```
pscale branch connections top <database> <branch>
```
— live read-only session inventory works for Postgres and Vitess over a reserved administrative connection. Do not cancel queries or terminate connections unless the operator explicitly approves that operational action.
Query Insights is public API. Live query telemetry:
```
.../branches/{branch}/insights
```
(per-pattern statistics; supports
```
from
```
/
```
to
```
/
```
period
```
,
```
q
```
,
```
sort
```
,
```
dir
```
,
```
tablet_type
```
,
```
type
```
,
```
fields
```
, and pagination). Related endpoints under the same branch path:
```
insights/errors
```
,
```
insights/anomalies
```
,
```
insights/tags
```
,
```
insights/tags/summaries
```
,
```
insights/{fingerprint}
```
(individual executions),
```
insights/{fingerprint}/summary
```
, and
```
insights/{fingerprint}/traffic/budgets
```
. The
```
query-patterns
```
path returns generated report metadata, not live patterns.

Traffic budgets:

.../branches/{branch}/traffic/budgets

. The CLI has no

pscale traffic-control budget list

; use the API for inventory.

Postgres roles: list via

.../branches/{branch}/roles

; fetch a single role by ID, not name (

pscale role get <db> <branch> <role-id>

IP restrictions: database-level
```
organizations/{org}/databases/{db}/cidrs
```
. Branch-level IP-restriction paths are not valid.
Schema recommendations: database-level
```
.../databases/{db}/schema-recommendations
```
(the branch-level path is not valid). Requesting
```
page=2
```
currently returns 404 even when the response reports
```
next_page
```
; use the database object's
```
open_schema_recommendations_count
```
as the authoritative total, treat the returned page as a sample, and state in the report when the itemized list covers only part of the total.
PITR state and branch-level backup policies have no verified read path; record backup posture from
```
pscale backup list
```
and the database-level backup policy, and mark PITR "not assessed in this run" rather than probing paths.
List endpoints paginate; follow the pagination parameters until exhausted before reporting counts (except the schema-recommendations case above).

Record access failures (403s, missing token scopes, timeouts) in the internal run log for the operator. They are not findings and do not enter the customer report (see

../10-customer-report-template/SKILL.md

所有命令和端点都必须以官方文档为依据，而非猜测。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>
```
—— org是一个标志，而非位置参数。
```
pscale api <path>
```
使用相对于组织的路径，例如
```
organizations/{org}/databases/{db}/branches/{branch}
```
—— 没有
```
get
```
子命令，也没有
```
/v1/
```
前缀。使用
```
-Q key=value
```
标志传递查询参数；在路径中嵌入
```
?
```
/
```
&
```
会在shell通配符下失效。

pscale webhook list <database> --org <org>

—— database是位置参数。

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
```
（分支级路径无效）。当前请求
```
page=2
```
即使响应报告
```
next_page
```
也会返回404；请使用数据库对象的
```
open_schema_recommendations_count
```
作为权威总数，将返回的页面视为样本，并在报告中说明分项列表仅覆盖总数的一部分。
PITR状态和分支级备份策略没有已验证的读取路径；请从
```
pscale backup list
```
和数据库级备份策略记录备份状态，并标记PITR“本次运行未评估”，而非探测路径。
列表端点支持分页；报告计数前请遍历所有分页参数（除上述架构建议情况外）。

将访问失败（403、缺少令牌权限、超时）记录在操作员的内部运行日志中。这些不属于发现的问题，也不会纳入客户报告（参见

../10-customer-report-template/SKILL.md

）。

Inventory checklist

盘点清单

Database identity

数据库标识

Record:

Organization.
Database.
Branch.
Engine: Vitess or Postgres.
Region and cloud provider.
Production/development branch status.
Branch protection and safe workflow state.
Size and cluster shape.

记录：

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

Branches and schema workflow

分支与架构工作流

For Vitess, record:

Production branch.
Whether safe migrations are enabled for production and staging branches.
Open deploy requests.
Deploy request approval setting.
Pending schema changes.
Whether branch strategy has a staging branch with safe migrations enabled.

For Postgres, record:

Branch list.
Whether branches were created from backup or empty.
Whether schema changes are managed manually, through migrations, or through an ORM.
Whether a separate branch is used for migration testing.
Whether the team expects Vitess-style deploy requests; if yes, flag that Postgres branches do not use deploy requests in the same way.

对于Vitess，记录：

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

对于Postgres，记录：

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

Observability

可观测性

Record:

Insights availability.
Whether query tags are present.
Which tags appear.
Whether high-cardinality tags are present.
Whether complete/raw query collection is enabled.
Active anomalies.
Query patterns with high latency, high rows read, high error rate, or high execution count.
Postgres CPU-heavy query patterns and Vitess vindex-usage data when exposed by the Insights interface in use.
Whether application deploy identifiers are visible in comments or tags.

记录：

Insights可用性。
是否存在查询标记。
出现的标记类型。
是否存在高基数标记。
是否启用完整/原始查询收集。
活跃异常。
具有高延迟、高读取行数、高错误率或高执行次数的查询模式。
当使用的Insights接口暴露时，Postgres CPU密集型查询模式和Vitess vindex使用数据。
应用部署标识符是否在注释或标记中可见。

Recommendations

建议

Record:

Open schema recommendations.
Recommendation type.
Affected table/query.
Proposed DDL or action.
Whether a branch/deploy workflow exists to evaluate it safely.
Whether the recommendation can be implemented as application code, ORM migration, or database DDL.

记录：

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

Webhooks and automation

Webhook与自动化

Record:

Configured webhooks.
Subscribed events.
Enabled state.
Last delivery success or failure.
Destination category: Slack, PagerDuty, internal automation, CI, agent queue, unknown.
Whether webhook signature verification is documented or implemented.
Whether webhook handling is idempotent and asynchronous.

记录：

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

Postgres Traffic Control

Postgres流量控制

For Postgres only, record:

Existing budgets and rules.
Budget modes: off, warn, enforce.
Limits: rate, capacity, burst, concurrency, warning threshold.
Rules by fingerprint, keyspace, query kind, or tags.
Whether rules are tied to meaningful SQLCommenter tags.
Whether any production budget is in enforce mode.

仅针对Postgres，记录：

现有预算和规则。
预算模式：关闭、警告、强制执行。
限制：速率、容量、突发、并发、警告阈值。
按指纹、键空间、查询类型或标记划分的规则。
规则是否与有意义的SQLCommenter标记关联。
是否有生产预算处于强制执行模式。

Postgres safety

Postgres安全性

For Postgres only, record:

Application role usage.
Whether apps use the default role.
Whether app roles are least-privilege.
Whether pg_strict is enabled for application roles.
Whether PgBouncer is used for appropriate workloads.
Whether live connections show blockers, idle-in-transaction sessions, or connection saturation during an active incident.
Whether private connectivity and IP restrictions are configured.
Whether backup retention and PITR meet the customer’s recovery expectations.

仅针对Postgres，记录：

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

Vitess safety

Vitess安全性

For Vitess only, record:

Safe migrations state.
Deploy request workflow.
Admin approval requirement.
Gated deployment usage.
Schema revert availability.
Branch and keyspace topology.
Sharding/vschema status.
Whether sharded query patterns use relevant vindexes.
Backups and restore posture.

仅针对Vitess，记录：

安全迁移状态。
部署请求工作流。
是否需要管理员审批。
是否使用 gated deployment。
架构回滚可用性。
分支和键空间拓扑。
分片/vschema状态。
分片查询模式是否使用相关的vindex。
备份和恢复状态。

Evidence format

证据格式

For every finding, include evidence:

Source: MCP, CLI, API, dashboard-observed, SQL read-only, repository file.
Path or command used.
Timestamp.
Raw value or concise excerpt.
Confidence: high, medium, low.

对于每个发现的内容，需包含证据：

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

Output

输出

Return:

Inventory table.
Missing evidence table.
Risk flags.
Recommended next skills to run.

End with:

“No changes have been applied.”

盘点表格。
缺失证据表格。
风险标记。
建议运行的后续技能。

结尾需包含：

“未应用任何更改。”