diff --git a/01-readonly-inventory/SKILL.md b/01-readonly-inventory/SKILL.md index ddca729..03d0a46 100644 --- a/01-readonly-inventory/SKILL.md +++ b/01-readonly-inventory/SKILL.md @@ -13,7 +13,8 @@ Build an evidence-backed inventory of a PlanetScale database without making chan Allowed by default: -- List organizations, databases, branches, keyspaces, regions, and sizes. +- List organizations, databases, branches, keyspaces, regions, branch sizes, + and Vitess read-only region cluster sizes and replica counts. - Read branch metadata. - Read webhook configuration. - Read schema recommendations. @@ -64,8 +65,12 @@ Verified interface notes (recheck against the docs when a command fails): administrative connection. Do not cancel queries or terminate connections 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. + `.../branches/{branch}/insights/anomalies`. The public Query Insights API + also exposes query statistics, per-fingerprint statistics and summaries, + query errors, anomalies, query tags, tag groupings, and Postgres traffic + budgets affecting a query fingerprint. Service tokens need `read_database` + permission for these endpoints. The `query-patterns` path returns generated + report metadata, not live patterns. - 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 @@ -105,7 +110,8 @@ Record: - Region and cloud provider. - Production/development branch status. - Branch protection and safe workflow state. -- Size and cluster shape. +- Size and cluster shape, including Vitess read-only region cluster sizes and + replica counts per keyspace when configured. ### Branches and schema workflow diff --git a/02-vitess-safety-review/SKILL.md b/02-vitess-safety-review/SKILL.md index 4160683..dd9fc73 100644 --- a/02-vitess-safety-review/SKILL.md +++ b/02-vitess-safety-review/SKILL.md @@ -70,6 +70,20 @@ Recommend a branch topology: Do not create branches without approval. +### Read-only regions and cluster shape + +Check: + +- Primary region and production branch size. +- Read-only regions configured for each keyspace. +- Cluster size and replica count for each Vitess read-only region. +- Whether application read traffic, analytics, agents, or regional workloads are + expected to use read-only regions. + +Recommend documenting the intended read topology before changing it. Read-only +region cluster size and replica count changes are behavior-changing capacity +changes requiring approval; do not apply them automatically. + ### Query Insights Review Insights for: diff --git a/04-query-insights-and-tags/SKILL.md b/04-query-insights-and-tags/SKILL.md index 5c04f9f..3b818bf 100644 --- a/04-query-insights-and-tags/SKILL.md +++ b/04-query-insights-and-tags/SKILL.md @@ -30,12 +30,19 @@ For the selected database and branch, inspect: over time. Treat missing or declining relevant-vindex usage as an indexing or routing investigation input, not as proof that a new index is required. -The Insights API (`.../branches/{branch}/insights`) returns hourly -pattern snapshots. Duration aggregates use field names like -`sum_total_duration_millis` — not `total_time_millis`. When the -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. +PlanetScale exposes Query Insights data through public API endpoints. +Use them for the dashboard-backed telemetry surfaces: query statistics, +per-fingerprint statistics and summaries, query errors, anomalies, query +tags and tag groupings, and Postgres traffic budgets affecting a query +fingerprint. Service tokens need `read_database` permission for these +endpoints. Verify exact paths in the OpenAPI reference before calling. + +The branch Insights endpoint (`.../branches/{branch}/insights`) returns +hourly pattern snapshots. Duration aggregates use field names like +`sum_total_duration_millis` — not `total_time_millis`. When the 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. ### Tag coverage diff --git a/05-traffic-control-recommendations/SKILL.md b/05-traffic-control-recommendations/SKILL.md index 5c99b13..b818df6 100644 --- a/05-traffic-control-recommendations/SKILL.md +++ b/05-traffic-control-recommendations/SKILL.md @@ -17,6 +17,8 @@ Before recommending rules, inspect: - Current budgets and rules. - Insights query patterns. +- For candidate Postgres fingerprints, any Query Insights API data showing + which traffic budgets already affect the fingerprint. - Current query tags. - Application routes and jobs. - Known critical paths. @@ -157,6 +159,8 @@ For each proposed budget: - Proposed tags or fingerprint. - Limit rationale. - Queries seen in Insights that justify it. +- Existing budgets already affecting the target fingerprint, if Query Insights + exposes that data. - Safety risk. - Test/observe plan. - Rollback plan. diff --git a/11-change-gates-and-approval-contract/SKILL.md b/11-change-gates-and-approval-contract/SKILL.md index 3b59865..d124250 100644 --- a/11-change-gates-and-approval-contract/SKILL.md +++ b/11-change-gates-and-approval-contract/SKILL.md @@ -58,7 +58,7 @@ Always requires explicit approval: - Change backup schedule or retention. - Create restore branch. - Create backup beyond automatic backups. -- Change branch size or replica topology. +- Change branch size, read-only region cluster size, or replica topology. - Edit repository files or dependencies. ### Class D: production data/availability impacting diff --git a/12-best-practices-matrix/SKILL.md b/12-best-practices-matrix/SKILL.md index a1b4029..51197fe 100644 --- a/12-best-practices-matrix/SKILL.md +++ b/12-best-practices-matrix/SKILL.md @@ -16,6 +16,10 @@ Map database findings to recommended PlanetScale features. Use this to ensure th Recommend for every production database: - Review slow, expensive, high-frequency, and erroring query patterns. +- Use public Query Insights API endpoints when automation needs dashboard-backed + query statistics, per-fingerprint summaries, query errors, anomalies, query + tags or tag groupings, or Postgres traffic budgets affecting a fingerprint. + Service tokens need `read_database` permission. - For Postgres, use CPU-sorted Insights data when diagnosing CPU pressure. - For sharded Vitess, review vindex usage per query pattern and the usage trend after index or routing changes. @@ -102,6 +106,14 @@ Recommend production, staging, and short-lived development branches with safe mi Recommend when query patterns or growth suggest shard-awareness problems. Do not reshard automatically. +### Read-only regions + +For Vitess databases with regional read traffic, analytics, agents, or other +replica-suitable workloads, review read-only regions per keyspace, including +cluster size and replica count. Recommend topology changes only with evidence +from workload placement, query volume, latency, or availability requirements; +do not apply read-only region size or replica changes automatically. + ## Postgres-specific recommendations ### User-defined roles