planetscale-readonly-inventory

Read-only inventory

Purpose

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

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.

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 ../planetscale-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.

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.

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.

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.

Webhooks and automation

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.

Postgres Traffic Control

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 safety

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.

Vitess safety

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.

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.

Output

Return:

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

End with:

“No changes have been applied.”