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).