Getting Started
Make sure to first set up your PlanetScale developer environment. Once you’ve installed thepscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.
The inspect command
Run read-only diagnostic checks against a database branch. Each check is a single bounded query against the engine’s statistics tables. Nothing is written to the database.
inspect uses the same ephemeral credential model as pscale sql: always read-only, always bounded. For server-side, traffic-aware analysis (slow queries, schema recommendations, anomalies), use pscale insights instead.
The two surfaces cross-reference each other in human output and JSON next_steps, so you can move from live state to traffic-aware history (or the reverse) without leaving the CLI.
Usage:
--org is required.
Database engine support
Checks adapt to the database engine. MySQL (Vitess) checks readinformation_schema, mysql, and sys. Postgres and Neki checks read pg_catalog and pg_stat views. Checks that do not apply to an engine explain what to use instead (often a matching pscale insights command).
On sharded Vitess databases, statistics reflect one shard’s MySQL instance per run. Pass
--keyspace to pick the keyspace, or target an exact shard with --keyspace 'mykeyspace/-80' (enumerate shards with SHOW VITESS_SHARDS via pscale sql). Databases can have hundreds of shards, so no check fans out across shards automatically.
On Postgres and Neki, pass --dbname to target the PostgreSQL database your application uses (defaults to postgres). The reader role may lack CONNECT on non-default databases; use --role admin if connecting with --dbname fails. Neki runs these checks through its router; use Query Insights for traffic-aware, cross-shard analysis.
Available checks
*
outliers and calls require the pg_stat_statements extension on PostgreSQL. If it is not installed, the check is skipped and points you at the matching pscale insights command.
Available flags
pscale inspect --replica uses the same Postgres |replica username suffix as pscale sql. That is not how Neki routes replica traffic. Do not add |replica to a Neki username.
Examples
Run a single check:JSON output
Individual checks return aCheckResult object with check, database, branch, columns, rows, row_count, and optional skipped and next_steps fields.
inspect all returns a Report with a results array (one entry per check) and top-level next_steps pointing at the complementary pscale insights commands.