Skip to content

Update skills for Query Insights report downloads #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cursor wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Update skills for Query Insights report downloads #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion 01-readonly-inventory/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,10 @@ Verified interface notes (recheck against the docs when a command fails):
unless the operator explicitly approves that operational action.
- Live query telemetry: `.../branches/{branch}/insights`. Anomalies:
`.../branches/{branch}/insights/anomalies`. The `query-patterns` path
returns generated report metadata, not live patterns.
returns generated report metadata, not live patterns. To create and download
a generated query-pattern report for Postgres or Vitess, use the CLI
`query-patterns download` subcommand with `--output <path>` and treat the CSV
as a report artifact.
- Traffic budgets: `.../branches/{branch}/traffic/budgets`. The CLI has no
`pscale traffic-control budget list`; use the API for inventory.
- Postgres roles: list via `.../branches/{branch}/roles`; fetch a single
Expand Down
7 changes: 7 additions & 0 deletions 04-query-insights-and-tags/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,13 @@ aggregation window is not explicit in the response, time-share
percentages within the returned window are more reliable than absolute
duration totals; prefer them for ranking.

When a workflow needs an offline or shareable report artifact instead of live
telemetry, download a Query Insights query-pattern report with
`pscale branch query-patterns download <database> <branch> --org <org> --output <path>`.
The command works for Postgres and Vitess branches and saves a CSV after report
generation completes. Use the CSV as report evidence; use the live Insights API
or MCP surfaces for current investigation loops.

### Tag coverage

For each expensive or anomalous query, determine:
Expand Down
3 changes: 3 additions & 0 deletions 12-best-practices-matrix/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ Recommend for every production database:
- Use tag filtering/navigation in Vitess Query Insights where available
(`tag:key:value`, Tags view, and per-execution tag drill-down).
- Use anomalies as alert and automation inputs.
- For audits, handoffs, or offline analysis, download Query Insights
query-pattern reports with `pscale branch query-patterns download` for
Postgres or Vitess and keep the CSV with the assessment evidence.

### Webhooks

Expand Down
25 changes: 20 additions & 5 deletions 14-pscale-cli-automation/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,20 @@
name: planetscale-pscale-cli-automation
description: >-
Use the PlanetScale CLI (pscale) from automated agents with --format json,
auth check, pscale sql, and per-command --force. Run before other PlanetScale
skills when driving pscale directly. Use when the user asks to automate
pscale, run CLI commands headless, or verify pscale auth from an agent.
auth check, pscale sql, Query Insights report downloads, and per-command
--force. Run before other PlanetScale skills when driving pscale directly. Use
when the user asks to automate pscale, run CLI commands headless, or verify
pscale auth from an agent.
---

# PlanetScale CLI automation

## Purpose

Teach agents how to invoke `pscale` non-interactively. This skill covers **CLI
conventions only**. Operational workflows (inventory, safety review, schema
recommendations) use the other skills in this repo — start with
conventions only**, including read-only report downloads. Operational workflows
(inventory, safety review, schema recommendations) use the other skills in this
repo — start with
`../00-safe-orchestrator/SKILL.md` for a full assessment.

## Two AGENTS.md files (do not confuse them)
Expand Down Expand Up @@ -64,6 +66,19 @@ pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"
MySQL uses `@primary` by default (same as `pscale shell`); pass `--keyspace` only
for multi-keyspace databases.

## Query Insights report downloads

For an offline or shareable Query Insights query-pattern report, use:

```bash
pscale branch query-patterns download <database> <branch> --org <org> --output <path>
```

The command works for Postgres and Vitess branches, creates the report, waits for
generation, and saves the CSV locally. Prefer an explicit `--output` path in
automation so downstream steps read a known artifact. Treat the CSV as generated
report evidence; use MCP/API Insights surfaces for live query-pattern telemetry.

## MCP vs CLI

- **MCP clients** — use the hosted PlanetScale MCP server (see `pscale agent-guide
Expand Down