PlanetScale CLI commands: insights

Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

The `insights` command

Surface PlanetScale’s server-side analysis of a database: aggregated query statistics, failing query patterns, resource anomalies, and schema recommendations, all computed from production traffic. For live, connection-level diagnostics (table sizes, locks, running queries), use pscale inspect instead. Query insights require Query Insights to be enabled for the database. See Postgres or Vitess. Postgres and Vitess branches are supported. Usage:

pscale insights <sub-command> <database> [<branch>] --org <org> <FLAG>

Place positional arguments first, then flags. --org is required.

Available sub-commands

Sub-command	Product	Description
`queries`	Postgres, Vitess	List top queries ranked by a performance metric
`queries samples`	Postgres, Vitess	List recent executions for a query fingerprint
`queries show`	Postgres, Vitess	Show one query execution by sample ID
`queries summary`	Postgres, Vitess	Show aggregate statistics for a query fingerprint
`queries traffic-budgets`	Postgres, Vitess	List traffic budgets that affect a query fingerprint
`errors`	Postgres, Vitess	List queries that are failing with errors
`errors show`	Postgres, Vitess	List the individual query executions that failed with an error fingerprint
`anomalies`	Postgres, Vitess	List detected resource anomalies (CPU, memory, IOPS, rows read/written)
`anomalies show`	Postgres, Vitess	Show one anomaly and the queries correlated with it
`tags`	Postgres, Vitess	List query tag keys (sqlcommenter / system)
`tags show`	Postgres, Vitess	Show a query tag key and its values
`tags summaries`	Postgres, Vitess	List query statistics grouped by tag keys
`recommendations`	Postgres, Vitess	List schema recommendations with ready-to-apply DDL
`recommendations show`	Postgres, Vitess	Show one schema recommendation and its full DDL
`recommendations dismiss`	Postgres, Vitess	Dismiss a schema recommendation

Available flags

Flag	Description
`--org <org>`	Organization name (required)
`-f`, `--format <FORMAT>`	Show output in a specific format. Possible values: `human` (default), `json`, `csv`.
`-h`, `--help`	Help for `insights`

Examples

The `queries` sub-command

List the top queries for a branch, ranked by cumulative execution time (default). Usage:

pscale insights queries <database> <branch> --org <org> <FLAG>

Available flags:

Flag	Description
`--sort <metric>`	Metric to rank by. One of: `totalTime`, `count`, `errorCount`, `rowsRead`, `rowsReturned`, `rowsAffected`, `rowsReadPerReturned`, `p50Latency`, `p99Latency`, `maxLatency`, `cpuTime`, `ioTime`, `lastRun`. Default: `totalTime`.
`--dir <direction>`	Sort direction: `asc` or `desc`. Default: `desc`.
`--limit <n>`	Number of queries to return. Default: `15`.
`--period <duration>`	Time period to aggregate over (for example `1h`, `24h`).

Examples:

pscale insights queries <database> <branch> --org <org>
pscale insights queries <database> <branch> --org <org> --sort rowsReadPerReturned
pscale insights queries <database> <branch> --org <org> --sort p99Latency --period 1h --format json

The `queries samples` sub-command

List recent executions for a specific query fingerprint. Use the fingerprint from pscale insights queries. --keyspace is required. Usage:

pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> <FLAG>

Available flags:

Flag	Description
`--keyspace <name>`	Keyspace for the fingerprint (required; from `insights queries`)
`--limit <n>`	Number of samples to return. Default: `25`.
`--period <duration>`	Time period to look back (for example `1h`, `1d`).

Example:

pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json

queries show takes an individual execution/sample id from queries samples. queries samples and queries summary take a query fingerprint. These identifiers are not interchangeable.

The `queries show` sub-command

Show one query execution using an ID returned by pscale insights queries samples.

pscale insights queries show <database> <branch> <query-id> --org <org>

The `queries summary` sub-command

Show aggregate statistics for a fingerprint from pscale insights queries. --keyspace is required (use the keyspace column from the queries list). Available flags:

Flag	Description
`--keyspace <name>`	Keyspace for the fingerprint (required; from `insights queries`)
`--period <duration>`	Named time period to summarize (for example `1h`, `12h`, or `1d`)
`--from <timestamp>`	Start of a custom time range as an ISO 8601 timestamp (use with `--to`)
`--to <timestamp>`	End of a custom time range as an ISO 8601 timestamp (use with `--from`)

--period cannot be combined with --from and --to. Both range flags must be set together.

pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace>
pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --period 1h

The `queries traffic-budgets` sub-command

List traffic budgets that affect a query fingerprint. Pass --keyspace from the queries list. The command is paginated; pass --page for the next page instead of walking every page automatically. Available flags:

Flag	Description
`--keyspace <name>`	Keyspace for the fingerprint (from `insights queries`)
`--page <n>`	Page of results to fetch.
`--per-page <n>`	Number of results per page. Default: `25`.

pscale insights queries traffic-budgets <database> <branch> <fingerprint> --org <org> --keyspace <keyspace>

The `errors` sub-command

List failing query patterns with error messages. Usage:

pscale insights errors <database> <branch> --org <org> <FLAG>

Available flags:

Flag	Description
`--limit <n>`	Number of errors to return. Default: `15`.
`--period <duration>`	Time period to aggregate over (for example `1h`, `24h`).

Example:

pscale insights errors <database> <branch> --org <org> --format json

`errors show`

List the individual executions that failed with an error fingerprint, including the users, keyspaces, and statements involved. Use the fingerprint column from insights errors (error_fingerprint in JSON), not the truncated id. Available flags:

Flag	Description
`--limit <n>`	Number of queries to return. Default: `25`.
`--period <duration>`	Time period to look back (for example `1h`, `1d`).

pscale insights errors show <database> <branch> <fingerprint> --org <org>
pscale insights errors show <database> <branch> <fingerprint> --org <org> --period 1h --limit 50

The `anomalies` sub-command

List detected resource anomalies for a branch. Usage:

pscale insights anomalies <database> <branch> --org <org> <FLAG>

`anomalies show`

Show one anomaly from insights anomalies, along with the queries whose activity correlates with it.

pscale insights anomalies show <database> <branch> <anomaly-id> --org <org>

The `tags` sub-command

List query tag keys from sqlcommenter / system tags on a branch. Usage:

pscale insights tags <database> <branch> --org <org> <FLAG>

Available flags:

Flag	Description
`--period <duration>`	Time period to look back (for example `1h`, `1d`).
`--fingerprint <fp>`	Only tags seen on this query fingerprint.
`--keyspace <name>`	Filter tags to a keyspace.
`--limit <n>`	Number of top values to show in human output. Default: `3`.

Example:

pscale insights tags <database> <branch> --org <org> --format json

`tags show`

Show a query tag key and its values.

pscale insights tags show <database> <branch> <tag> --org <org>

`tags summaries`

List query statistics grouped by one or more tag keys. --tags is required and repeatable.

pscale insights tags summaries <database> <branch> --org <org> --tags username --tags app --format json

The `recommendations` sub-command

List schema recommendations for a database: unused tables and indexes, duplicate indexes, bloated tables and indexes, missing indexes derived from production query patterns, and sequence overflow risks. Each recommendation includes ready-to-apply DDL in JSON output. This sub-command takes a database name only (not a branch). Usage:

pscale insights recommendations <database> --org <org> <FLAG>

Example:

pscale insights recommendations <database> --org <org> --format json

`recommendations show`

Show a single schema recommendation, including the full ready-to-apply DDL. <number> is the recommendation sequence number from pscale insights recommendations, the same value used by recommendations dismiss.

pscale insights recommendations show <database> <number> --org <org>

`recommendations dismiss`

Dismiss a schema recommendation. Use the recommendation number from pscale insights recommendations. Interactive confirmation is required unless --force is passed.

pscale insights recommendations dismiss <database> <number> --org <org> --force --reason "not applicable"

If the database or branch is not found, or Query Insights is not enabled, the command returns an error explaining both possible causes.

pscale inspect

Query Insights (Postgres)

Query Insights (Vitess)

Schema recommendations (Postgres)

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.

Introduction

Using the pscale CLI

CLI command reference

PlanetScale CLI commands: insights

Getting Started

The `insights` command

Available sub-commands

Available flags

Examples

The `queries` sub-command

The `queries samples` sub-command

The `queries show` sub-command

The `queries summary` sub-command

The `queries traffic-budgets` sub-command

The `errors` sub-command

`errors show`

The `anomalies` sub-command

`anomalies show`

The `tags` sub-command

`tags show`

`tags summaries`

The `recommendations` sub-command

`recommendations show`

`recommendations dismiss`

pscale inspect

Query Insights (Postgres)

Query Insights (Vitess)

Schema recommendations (Postgres)

Need help?

​Getting Started

​The insights command

​Available sub-commands

​Available flags

​Examples

​The queries sub-command

​The queries samples sub-command

​The queries show sub-command

​The queries summary sub-command

​The queries traffic-budgets sub-command

​The errors sub-command

​errors show

​The anomalies sub-command

​anomalies show

​The tags sub-command

​tags show

​tags summaries

​The recommendations sub-command

​recommendations show

​recommendations dismiss

​Related documentation

pscale inspect

Query Insights (Postgres)

Query Insights (Vitess)

Schema recommendations (Postgres)

​Need help?

Getting Started

The `insights` command

Available sub-commands

Available flags

Examples

The `queries` sub-command

The `queries samples` sub-command

The `queries show` sub-command

The `queries summary` sub-command

The `queries traffic-budgets` sub-command

The `errors` sub-command

`errors show`

The `anomalies` sub-command

`anomalies show`

The `tags` sub-command

`tags show`

`tags summaries`

The `recommendations` sub-command

`recommendations show`

`recommendations dismiss`

Related documentation

Need help?