Add pscale insights and pscale inspect commands for database diagnostics

[nickvanw]

Summary

Adds two complementary read-only diagnostic surfaces to the CLI, for both MySQL/Vitess and PostgreSQL databases:

• pscale insights — surfaces PlanetScale's server-side analysis of production traffic, which until now was only reachable through the MCP server or raw pscale api calls:
  • insights queries <db> <branch> — top queries ranked by any insights metric (--sort totalTime|count|p99Latency|rowsRead|rowsReadPerReturned|…, plus --period, --dir, --limit)
  • insights errors <db> <branch> — failing query patterns with error messages
  • insights anomalies <db> <branch> — detected resource anomalies
  • insights recommendations <db> — schema recommendations with ready-to-apply DDL
• pscale inspect — live, point-in-time checks run over a direct connection using the same ephemeral-credential model as pscale sql (always read-only, always bounded): table-sizes, index-sizes, unused-indexes, redundant-indexes, invalid-indexes, seq-scans, long-running-queries, locks, outliers, calls, bloat, vacuum-stats, replication-slots, subscriptions — and inspect all, which runs every applicable check over a single connection and prints a combined report.

All commands support --format json (and csv for single checks) for scripting and agents. Every command's --help ends with a footer pointing agents at pscale agent-guide --format json, and the embedded guide is readable via pscale help agents.

Why

Users (and increasingly, AI agents) diagnosing a slow or unhealthy database today have to bounce between the web app, the MCP server, and hand-written SQL through pscale shell. The platform already computes rich, traffic-aware analysis — query stats, anomalies, schema recommendations — but none of it was exposed as first-class CLI commands, and there was no safe, canned way to ask the database itself the standard DBA questions (what's big, what's unused, what's locked, what's bloated).

This gives both audiences a single obvious front door. The two surfaces deliberately cross-reference each other (help text, human output, and next_steps in JSON) so an agent that lands on either one discovers the other: insights for historical, traffic-aware analysis; inspect for live state and physical layout. When a check isn't available for an engine — or needs a PostgreSQL extension that isn't installed (e.g. outliers needs pg_stat_statements) — the output points at the insights command that answers the same question server-side with no setup.

Changes

• internal/planetscale/insights.go — new QueryInsights service (ListQueries/ListErrors/ListAnomalies) plus WithSort/WithPeriod list options; the already-present SchemaRecommendations service is now actually used by a command
• internal/cmd/insights/ — the four insights subcommands
• internal/cmd/inspect/ — check catalog (per-engine SQL with invariants enforced by tests: single statement, read-only, LIMIT-bounded, system/internal schemas filtered) and the command tree
• internal/sqlquery/session.go — reusable Session (one connection, many queries) extracted from Execute; connection setup for both engines refactored into openMySQL/openPostgres with no behavior change to pscale sql
• internal/printer — expose the resource writer so commands with dynamic column sets can render CSV
• AGENTS.md — documents both surfaces and when to use which

The PostgreSQL query catalog was sharpened from review feedback:

• table-sizes uses pg_table_size (heap + TOAST + FSM + VM; indexes are itemized by index-sizes, so counting them here would double-count), rolls partitions up into their root, and includes materialized views
• index-sizes names indexes as table.index
• long-running-queries excludes walsenders (replication connections are "active" forever and made the check permanently noisy) and bounds query text
• locks reports only the roots of blocking trees via pg_blocking_pids() with a count of sessions stuck behind each, instead of dumping every granted lock
• bloat covers index bloat as well as table bloat, with object size and a bloat percentage
• vacuum-stats honors per-table autovacuum reloptions (including autovacuum_enabled=false, reported as disabled) and tracks analyze alongside vacuum
• replication-slots separates retained WAL from unconfirmed WAL and adds wal_status/safe_wal_size (headroom before max_slot_wal_keep_size invalidates the slot)
• invalid-indexes is a new check for indexes left invalid by failed CREATE INDEX CONCURRENTLY builds

Notes for reviewers:

• On sharded Vitess databases, inspect statistics reflect one shard's MySQL instance per run. --keyspace accepts vtgate shard targets (mykeyspace/-80, mykeyspace/-80@replica) to pin an exact shard — shard-targeted connections bypass the planner and read that shard's statistics directly. Enumerate shards with SHOW VITESS_SHARDS. Databases can have hundreds of shards, so nothing fans out automatically.
• On PostgreSQL, stats are scoped to one database; --dbname selects it, and the reader role can lack CONNECT on non-default databases — the error suggests --role admin.
• All queries verified live against a sharded Vitess database and PostgreSQL databases (all three output formats, extension-missing and engine-mismatch paths).

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7d4f593. Configure here.}