Use PlanetScale's server-side analysis of production traffic to investigate query performance and schema health. These commands complement the point-in-time, connection-level checks in pscale inspect.
Common commands
# Rank queries by cumulative execution time (default sort)
pscale insights queries <database> <branch> --org <org> --format json
# Find inefficient read patterns over the last day
pscale insights queries <database> <branch> --org <org> \
--sort rowsReadPerReturned --period 1d --limit 25 --format json
# Find high-tail-latency queries over the last hour
pscale insights queries <database> <branch> --org <org> \
--sort p99Latency --period 1h --format json
Drill into recent executions using fingerprint and keyspace from the query list
pscale insights queries samples --org
--keyspace --period 1h --limit 25 --format json
pscale insights queries show --org --format json
pscale insights queries summary --org
--keyspace --period 1h --format json
pscale insights queries traffic-budgets --org
--keyspace --page 1 --per-page 25 --format json
pscale insights tags --org --format json
pscale insights tags summaries --org
--tags username --tags app --sort totalTime --format json
pscale insights errors --org --period 1d --format json pscale insights errors show --org --period 1d --format json pscale insights anomalies --org --format json pscale insights anomalies show --org --format json
Review database-level schema recommendations and their proposed DDLpscale insights recommendations --org --format json pscale insights recommendations show --org --format json
Always pass `--org` explicitly in agent workflows so the organization target is unambiguous. Prefer `--format json` so full normalized SQL, metrics, recommendation details, and proposed DDL remain machine-readable.
## Query ranking
`pscale insights queries` defaults to `--sort totalTime --dir desc --limit 15`. Supported sort keys are:
- `totalTime`, `count`, `errorCount`
- `rowsRead`, `rowsReturned`, `rowsAffected`, `rowsReadPerReturned`
- `p50Latency`, `p99Latency`, `maxLatency`
- `cpuTime`, `ioTime`, `lastRun`
Use `--dir asc|desc`, `--limit <n>`, and an API-supported period such as `1h` or `1d` to keep comparisons explicit. Do not compare differently scoped periods as though they represented the same workload.
## Execution samples
Each JSON record from `pscale insights queries` includes a `fingerprint` and `keyspace`. Pass both to `queries samples`; `--keyspace` is required because the same fingerprint can exist in more than one keyspace.
Samples expose individual executions, including start time, duration, user, rows read/returned, normalized SQL, errors, and attached tags. Use them to validate whether an aggregate represents one outlier or a recurring pattern. Query samples can contain sensitive SQL context, usernames, addresses, or tag values, so do not paste raw output into public issues or logs without review.
`queries show` reads one query execution by query ID. `queries summary` reads fingerprint-level aggregate statistics for one fingerprint/keyspace/time window. `queries traffic-budgets` lists Traffic Control budgets that apply to one fingerprint/keyspace and is paginated; empty later pages mean no rows on that page, not necessarily that no budget exists.
```bash
pscale insights queries show <database> <branch> <query-id> --org <org> --format json
pscale insights queries summary <database> <branch> <fingerprint> \
--org <org> --keyspace <keyspace> --period 1h --format json
pscale insights queries traffic-budgets <database> <branch> <fingerprint> \
--org <org> --keyspace <keyspace> --page 1 --per-page 25 --format json
Use the exact query ID, fingerprint, and keyspace returned by Insights. These Insights commands forward identifiers to the API as-is, and metrics query selectors are also forwarded opaquely; if a command returns no data or not-found, verify the selector before concluding the query had no activity or budgets.
Error and anomaly details
The human errors table displays the full fingerprint. For JSON automation, copy error_fingerprint from the list and pass it unchanged to errors show; do not use a shortened display ID. The detail command returns individual failed executions, including users, keyspaces, statements, and error messages.
pscale insights errors <database> <branch> --org <org> --period 1h --format json
pscale insights errors show <database> <branch> <error_fingerprint> \
--org <org> --period 1h --limit 25 --format json
anomalies show returns one anomaly plus queries whose activity correlates with it. Correlation is evidence for investigation, not proof that a query caused the resource event.
pscale insights anomalies <database> <branch> --org <org> --format json
pscale insights anomalies show <database> <branch> <anomaly-id> \
--org <org> --format json
Treat detailed executions and normalized SQL as potentially sensitive. Compare the anomaly interval with query timing, metrics, and application changes before proposing a fix.
Query tags
Use pscale insights tags to list observed sqlcommenter and system tag keys. The command returns friendly names matching the PlanetScale Insights UI, such as app, controller, and username.
# Show values observed for one friendly tag name
pscale insights tags show <database> <branch> app --org <org> --period 1h --format json
# Group workload by one or more repeatable tag keys
pscale insights tags summaries <database> <branch> --org <org> \
--tags app --tags controller --sort p99Latency --period 1d --format json
List tags before using show or summaries. Pass friendly names, not internal S.../B... IDs. If a friendly name exists in both sources, disambiguate it as sql:<name> or system:<name>. Optional --fingerprint and --keyspace filters on tags narrow attribution to the intended query or keyspace.
Investigation workflow
- Confirm the organization, database, branch, and time window.
- Rank queries by the metric related to the symptom (
totalTime,p99Latency,rowsReadPerReturned, orerrorCount). - Use the returned fingerprint and keyspace to inspect recent
queries sampleswhen execution-level evidence is needed. - List and summarize query tags to attribute the workload to applications, controllers, users, or other observed dimensions.
- Inspect
errorsandanomaliesfor the same branch and time window, then drill into the relevant full error fingerprint or anomaly ID. - Use
queries summary,queries show, orqueries traffic-budgetswhen one query needs execution detail, aggregate context, or Traffic Control attribution. - Run
pscale inspect all <database> <branch> --org <org> --format jsonfor live connection-level evidence. - Review database-level
recommendationsandrecommendations showfor index, bloat, and sequence-risk findings. - Summarize evidence separately from proposed changes.
A not-found response for branch-scoped insights can mean the database/branch does not exist or Query Insights is not enabled. Verify both before concluding that there is no data.
Recommendation safety
Recommendations can include ready-to-apply DDL in JSON output. Use pscale insights recommendations show <database> <number> to inspect one recommendation and its full DDL before proposing action. Treat that DDL as a proposal, not an instruction to execute automatically:
- Confirm engine, keyspace/schema, table, and production target.
- Check whether an index is still required by a low-frequency or seasonal workload.
- Review lock/runtime impact and use a branch plus deploy-request workflow where supported.
- Obtain explicit user approval before executing schema changes.
- Verify the result and keep a rollback plan.
Dismissal is also a write: pscale insights recommendations dismiss <database> <number>. Confirm the organization, database, and recommendation sequence number from the current list/show output, explain why the finding is inapplicable, and obtain explicit approval before dismissing it. Prefer an informative --reason; use --force only for already-approved non-interactive execution, then verify the recommendation state.
Related skills
- pscale-inspect — point-in-time, read-only diagnostics against one database connection target
- pscale-sql — deliberate one-off SQL queries with role and destructive-query safeguards
- pscale-deploy-request — reviewed Vitess/MySQL schema deployment workflow
References
See references/commands.md for the verified command synopsis and flags.