From d05a0801539df9225c67855d9936c0d4763897d6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 8 Jul 2026 07:04:10 +0000 Subject: [PATCH] Update skills for query pattern report downloads Co-authored-by: Sam Lambert --- 01-readonly-inventory/SKILL.md | 5 ++++- 04-query-insights-and-tags/SKILL.md | 7 +++++++ 12-best-practices-matrix/SKILL.md | 3 +++ 14-pscale-cli-automation/SKILL.md | 25 ++++++++++++++++++++----- 4 files changed, 34 insertions(+), 6 deletions(-) diff --git a/01-readonly-inventory/SKILL.md b/01-readonly-inventory/SKILL.md index ddca729..f320351 100644 --- a/01-readonly-inventory/SKILL.md +++ b/01-readonly-inventory/SKILL.md @@ -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 ` 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 diff --git a/04-query-insights-and-tags/SKILL.md b/04-query-insights-and-tags/SKILL.md index 5c04f9f..5013917 100644 --- a/04-query-insights-and-tags/SKILL.md +++ b/04-query-insights-and-tags/SKILL.md @@ -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 --org --output `. +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: diff --git a/12-best-practices-matrix/SKILL.md b/12-best-practices-matrix/SKILL.md index a1b4029..e1e0db2 100644 --- a/12-best-practices-matrix/SKILL.md +++ b/12-best-practices-matrix/SKILL.md @@ -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 diff --git a/14-pscale-cli-automation/SKILL.md b/14-pscale-cli-automation/SKILL.md index 9e87157..4b4d889 100644 --- a/14-pscale-cli-automation/SKILL.md +++ b/14-pscale-cli-automation/SKILL.md @@ -2,9 +2,10 @@ 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 @@ -12,8 +13,9 @@ description: >- ## 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) @@ -64,6 +66,19 @@ pscale sql --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 --org --output +``` + +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