Skip to main content

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, Vitess, or Neki. Usage:
Place positional arguments first, then flags. --org is required.

Available sub-commands

Available flags

Examples

The queries sub-command

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

The queries samples sub-command

List recent executions for a specific query fingerprint. Use the fingerprint from pscale insights queries. --keyspace is required. Usage:
Available flags: Example:
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.

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: --period cannot be combined with --from and --to. Both range flags must be set together.

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:

The errors sub-command

List failing query patterns with error messages. Usage:
Available flags: Example:

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:

The anomalies sub-command

List detected resource anomalies for a branch. Usage:

anomalies show

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

The tags sub-command

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

tags show

Show a query tag key and its values.

tags summaries

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

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:
Example:

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.

recommendations dismiss

Dismiss a schema recommendation. Use the recommendation number from pscale insights recommendations. Interactive confirmation is required unless --force is passed.
If the database or branch is not found, or Query Insights is not enabled, the command returns an error explaining both possible causes.

The agent sub-command

Start and review Insights Agent runs and schedules. The agent reviews slow queries or implements schema recommendations against the repository connected to a database, and opens a pull request with the changes it makes. Runs belong to a branch. Each run reviews up to five slow query patterns or implements up to five schema recommendations from that branch. The database needs a connected repository. If the branch is not found, or the Insights Agent is not enabled for the organization, the command returns an error explaining both possible causes. Usage:

agent runs

List Insights Agent runs on a branch, newest first. Available flags: --keyspace requires --fingerprint.

agent runs show

Show an Insights Agent run, its stages, and the pull request it opened. <number> is the run number from pscale insights agent runs.

agent runs create

Start an Insights Agent run on a branch. The database needs a connected repository, and the agent opens a pull request against it with the changes it makes. Pass up to five slow query fingerprints with --fingerprint and their --keyspace to review slow queries, or up to five schema recommendation numbers with --schema-recommendation to implement them. Find fingerprints with pscale insights queries and recommendation numbers with pscale insights recommendations. --fingerprint and --schema-recommendation cannot be combined. Pass one of the two, not both. Available flags: --fingerprint and --keyspace must be passed together.

agent runs cancel

Cancel a pending or running Insights Agent run. Interactive confirmation is required unless --force is passed.

agent runs feedback

Rate a completed Insights Agent run. Rating a run again replaces your earlier rating. Available flags:

agent schedules

List the Insights Agent schedules on a branch.

agent schedules update

Turn on, turn off, or change when the Insights Agent runs on its own for one run type on a branch. <run-type> is slow_query or schema_recommendation. Scheduled runs choose their own targets: slow query runs look at the queries Insights recorded in the last 24 hours, and schema recommendation runs work on the branch’s open recommendations. A run with nothing to work on is skipped. Flags that are not passed keep their current value. At least one of the flags below is required. Available flags:

pscale inspect

Insights Agent

Query Insights (Postgres)

Query Insights (Vitess)

Query Insights (Neki)

Anomalies (Neki)

Schema recommendations (Postgres)

Schema recommendations (Neki)

Need help?

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