> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale CLI commands: inspect

Vitess, Neki, and Postgres

## Getting Started

Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup.md). Once you've installed the `pscale` 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`](/docs/cli/sql): always read-only, always bounded. For server-side, traffic-aware analysis (slow queries, schema recommendations, anomalies), use [`pscale insights`](/docs/cli/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:**

```bash theme={null}
pscale inspect <check> <database> <branch> --org <org> <FLAG>
```

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

### Database engine support

Checks adapt to the database engine. MySQL (Vitess) checks read `information_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).

| | **Postgres and Neki** | **Vitess** |
| :- | :- | :- |
| Targeting flags | `--dbname`, `--role` | `--keyspace` |
| Scope | One PostgreSQL database per run | One shard's MySQL instance per run |
| Replica checks | `--replica` for Postgres. For Neki, use [`pscale shell --replica`](/docs/cli/shell). | `--replica` (via `--keyspace` tablet type) |

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

| **Check** | **Postgres and Neki** | **Vitess** | **Description** |
| :- | :- | :- | :- |
| `table-sizes` | Yes | Yes | Tables by total size, largest first |
| `index-sizes` | Yes | Yes | Indexes by size, largest first |
| `unused-indexes` | Yes | Yes | Indexes with little or no use — removal candidates |
| `redundant-indexes` | Via `insights recommendations` | Yes | Indexes made redundant by another index |
| `invalid-indexes` | Yes | No | Invalid indexes left over from failed concurrent index builds |
| `seq-scans` | Yes | Yes | Tables receiving full-table scans |
| `long-running-queries` | Yes | Yes | Queries running longer than 5 minutes |
| `locks` | Yes | Yes | Blocking locks and the sessions stuck behind them |
| `outliers` | Yes\* | Via `insights queries` | Queries by cumulative execution time |
| `calls` | Yes\* | Via `insights queries` | Most frequently called queries |
| `bloat` | Yes | Yes | Wasted space: estimated bloat (PostgreSQL) or fragmentation (MySQL) |
| `vacuum-stats` | Yes | Via `inspect bloat` | Autovacuum and autoanalyze health |
| `replication-slots` | Yes | Via `branch vtctl move-tables list` | Replication slots: status, WAL retention, and lag |
| `subscriptions` | Yes | Via `branch vtctl move-tables list` | Per-table logical replication progress on this subscriber |
| `all` | Yes | Yes | Run every applicable check and print a combined report |

\* `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

| **Flag** | **Description** |
| - | - |
| `--org <org>` | Organization name **(required)** |
| `--keyspace <target>` | Vitess keyspace to inspect, optionally with a shard and tablet type (for example `mykeyspace`, `mykeyspace/-80`, `mykeyspace/-80@replica`). Defaults to `@primary`. |
| `--dbname <name>` | Postgres or Neki database name to inspect. Default: `postgres`. |
| `--role <role>` | Access role for ephemeral credentials: `reader`, `writer`, `readwriter`, or `admin`. Default: `reader`. |
| `--replica` | Run checks against a replica instead of the primary for PlanetScale Postgres or Vitess. For Neki, use [`pscale shell --replica`](/docs/cli/shell), which sets `__neki.target=REPLICA`. |
| `-f`, `--format <FORMAT>` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. `csv` is supported for individual checks only, not `inspect all`. |
| `-h`, `--help` | Help for `inspect` |

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

```bash theme={null}
pscale inspect table-sizes <database> <branch> --org <org>
pscale inspect locks <database> <branch> --org <org> --format json
pscale inspect unused-indexes <database> <branch> --org <org> --format csv
```

Run every applicable check:

```bash theme={null}
pscale inspect all <database> <branch> --org <org>
pscale inspect all <database> <branch> --org <org> --format json
```

Target a specific Vitess shard:

```bash theme={null}
pscale inspect table-sizes <database> <branch> --org <org> --keyspace commerce/-80
```

Inspect a non-default PostgreSQL database:

```bash theme={null}
pscale inspect table-sizes <database> <branch> --org <org> --dbname myapp --role admin
```

### JSON output

Individual checks return a `CheckResult` 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.

## Related documentation

> **[pscale insights](/docs/cli/insights.md)**

> **[pscale sql](/docs/cli/sql.md)**

> **[PlanetScale CLI environment setup](/docs/cli/planetscale-environment-setup.md)**

## Need help?

Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.