diff --git a/01-readonly-inventory/SKILL.md b/01-readonly-inventory/SKILL.md index e646194..0c8df21 100644 --- a/01-readonly-inventory/SKILL.md +++ b/01-readonly-inventory/SKILL.md @@ -22,11 +22,13 @@ Allowed by default: - Read Postgres roles and non-secret role metadata. - Read backup schedules and restore metadata. - Read branch schema. +- Read database and branch deletion-protection state. +- Inspect deploy request queue, operation, and deployment details. - Inspect live connection/session metadata with the Connections CLI view. - Inspect repository files for frameworks, ORMs, migrations, SQL tagging, and connection config. - Inspect Terraform or other infrastructure-as-code definitions for - PlanetScale roles, backups, backup policies, Postgres parameters, and - supported extensions. + PlanetScale roles, backups, backup policies, deletion protection, Postgres + parameters, and supported extensions. Not allowed without explicit approval: @@ -74,6 +76,11 @@ Verified interface notes (recheck against the docs when a command fails): 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. +- Vitess deploy request inspection: `pscale deploy-request queue `, + `pscale deploy-request operations `, and + `pscale deploy-request deployment ` are read-only + inventory commands. `pscale deploy-request throttler update ...` is a + mutation and is outside read-only inventory. - Postgres roles: list via `.../branches/{branch}/roles`; fetch a single role by ID, not name (`pscale role get `). - IP restrictions: database-level @@ -111,6 +118,7 @@ Record: - Region and cloud provider. - Production/development branch status. - Branch protection and safe workflow state. +- Database and branch deletion-protection state. - Size and cluster shape. ### Branches and schema workflow @@ -120,13 +128,17 @@ For Vitess, record: - Production branch. - Whether safe migrations are enabled for production and staging branches. - Open deploy requests. +- Active deploy request queue position, operations, deployment progress, and + throttler settings when a deploy request is in flight. - Deploy request approval setting. - Pending schema changes. +- Deletion-protection state for production and other long-lived branches. - Whether branch strategy has a staging branch with safe migrations enabled. For Postgres, record: - Branch list. +- Deletion-protection state for production and other long-lived branches. - Whether branches were created from backup or empty. - Whether schema changes are managed manually, through migrations, or through an ORM. - Whether a separate branch is used for migration testing. diff --git a/02-vitess-safety-review/SKILL.md b/02-vitess-safety-review/SKILL.md index 09618a6..69692f2 100644 --- a/02-vitess-safety-review/SKILL.md +++ b/02-vitess-safety-review/SKILL.md @@ -34,6 +34,8 @@ Check: - Whether teams use gated deployments for cutover control. - Whether “deploy instantly” is used and whether the team understands it removes the gated-deployment/revert shape. - Whether cutover is regularly delayed by long-running transactions. +- Whether active deploy requests have clear queue, operation, deployment, and + throttler state when they are being monitored or tuned. - Whether deploy request events are subscribed to via webhooks. Recommend: @@ -46,6 +48,10 @@ Recommend: approval permission. - Prefer normal safe deployments over instant deployments unless the migration is known to be instant-safe and the rollback story is acceptable. - Use gated deployment when cutover timing matters. +- Use `pscale deploy-request queue`, `operations`, and `deployment` as + read-only evidence when diagnosing active deploys. Treat per-request + throttler updates as operational changes that require approval, especially + when production traffic is affected. - Treat “force cutover now” as an operator-controlled action for delayed cutovers: it aggressively stops running transactions to complete schema cutover. Recommend reviewing the blocking workload and incident context @@ -71,9 +77,27 @@ Recommend a branch topology: - `staging` branch based from production with safe migrations enabled. - Short-lived development branches based from staging. - Deploy requests from development to staging, then staging to production when appropriate. +- Deletion protection enabled on the database and on production or other + long-lived branches where accidental removal would be disruptive. Do not create branches without approval. +### Deletion protection + +Check whether deletion protection is enabled on the database and on critical +branches. + +Recommend: + +- Enable deletion protection for production databases, production branches, and + other long-lived branches that should not be removable in a single step. +- If Terraform manages branches, keep `deletion_protected` in Terraform for + `planetscale_vitess_branch` resources so disabling protection is reviewed as + infrastructure code before a branch resource can be removed. + +Do not disable deletion protection or delete protected resources without +explicit approval and target confirmation. + ### Query Insights Review Insights for: diff --git a/03-postgres-safety-review/SKILL.md b/03-postgres-safety-review/SKILL.md index 14e4ed8..9d90d79 100644 --- a/03-postgres-safety-review/SKILL.md +++ b/03-postgres-safety-review/SKILL.md @@ -17,6 +17,8 @@ Check: - Whether a development or test branch exists. - Whether branches are empty or restored from backup. +- Whether deletion protection is enabled for the database and critical + branches. - Whether migrations are tested against a branch before production. - Whether application migrations are reversible or have a documented rollback strategy. - Whether production DDL is manually reviewed. @@ -27,8 +29,14 @@ Recommend: - Run migration validation and application tests against that branch. - Treat production migration application as an explicit human-approved deployment step. - Use PITR/backup restore branches for incident recovery, not as an automatic rollback mechanism. - -Do not create branches, run migrations, or restore backups without approval. +- Enable deletion protection for production databases, production branches, and + other long-lived branches that should not be removable in a single step. +- If Terraform manages branches, keep `deletion_protected` in Terraform for + `planetscale_postgres_branch` resources so disabling protection is reviewed + as infrastructure code before a branch resource can be removed. + +Do not create branches, run migrations, disable deletion protection, delete +protected resources, or restore backups without approval. ## Roles and least privilege diff --git a/07-schema-recommendations-agent-loop/SKILL.md b/07-schema-recommendations-agent-loop/SKILL.md index 4a2d836..2a6435c 100644 --- a/07-schema-recommendations-agent-loop/SKILL.md +++ b/07-schema-recommendations-agent-loop/SKILL.md @@ -55,9 +55,12 @@ Recommended path: 2. Apply the schema change to that branch only after approval. 3. Open a deploy request only after approval. 4. Use deploy request review to inspect schema, shard impact, data-loss warnings, lint errors, and conflicts. -5. Use normal safe migration path unless instant deployment is explicitly justified. -6. Deploy only after approval. -7. Monitor Insights and anomaly state after deployment. +5. When monitoring an active deploy request, use queue, operations, and + deployment inspection as read-only evidence before proposing any throttler + change. +6. Use normal safe migration path unless instant deployment is explicitly justified. +7. Deploy only after approval. +8. Monitor Insights and anomaly state after deployment. Default output before approval: issue or PR with migration proposal, not a live deploy request. diff --git a/09-mcp-agent-operating-model/SKILL.md b/09-mcp-agent-operating-model/SKILL.md index e419215..fbd8674 100644 --- a/09-mcp-agent-operating-model/SKILL.md +++ b/09-mcp-agent-operating-model/SKILL.md @@ -53,6 +53,8 @@ Allowed by default: - Read schema metadata. - Read existing webhooks and Traffic Control configuration. - Read branch metadata. +- Read deletion-protection state. +- Inspect deploy request queue, operations, and deployment details. - Inspect repository code. - Correlate query patterns with code. - File issues. @@ -80,6 +82,8 @@ Not allowed by default (the review-gate actions and non-reviewable mutations): - Rotate credentials. - Change roles. - Change IP restrictions or private connectivity. +- Change deploy request throttler settings. +- Disable deletion protection. - Restore or promote branches. ## Agent loops @@ -158,7 +162,8 @@ for the same fingerprint/recommendation ID). covers only the mechanical deploy. - **Branch hygiene** (weekly): delete development branches older than the authorized age bound with no open deploy request; never touch - production or protected branches. + production or deletion-protected branches, and never disable deletion + protection to make a branch eligible for hygiene deletion. - **Warn-budget gardener** (weekly): create warn-mode Traffic Control budgets for newly identified expensive slices matching the allowlist; report warn counts on existing budgets. Enforce mode is never entered diff --git a/11-change-gates-and-approval-contract/SKILL.md b/11-change-gates-and-approval-contract/SKILL.md index 3b59865..962d183 100644 --- a/11-change-gates-and-approval-contract/SKILL.md +++ b/11-change-gates-and-approval-contract/SKILL.md @@ -16,6 +16,7 @@ Prevent accidental or autonomous changes that can affect availability, safety, s Allowed without approval: - List databases, branches, keyspaces, webhooks, backups, roles, traffic budgets, schema recommendations, deploy requests, and Insights data. +- Inspect deploy request queue, operations, deployment details, and deletion-protection state. - Inspect repository code. - Read schema metadata. - Read non-sensitive database metadata. @@ -56,6 +57,8 @@ Always requires explicit approval: - Change connection pooling behavior. - Change IP restrictions, PrivateLink, PSC, or public access. - Change backup schedule or retention. +- Enable deletion protection, or disable deletion protection on non-production targets. +- Adjust deploy request throttler settings on non-production targets. - Create restore branch. - Create backup beyond automatic backups. - Change branch size or replica topology. @@ -69,7 +72,9 @@ Requires explicit approval, named target confirmation, rollback plan, and ideall - Production DML. - Applying schema recommendation to production. - Queueing or applying Vitess deploy request to production. +- Adjusting deploy request throttler settings for a production deploy request. - Promoting or restoring branches. +- Disabling deletion protection on a production database or branch. - Deleting branches, databases, roles, webhooks, backups, or traffic rules. - Enforcing Traffic Control on production. - Changing production network access. diff --git a/12-best-practices-matrix/SKILL.md b/12-best-practices-matrix/SKILL.md index ce47f93..5da23d2 100644 --- a/12-best-practices-matrix/SKILL.md +++ b/12-best-practices-matrix/SKILL.md @@ -68,6 +68,16 @@ Recommend: - Test before production. - Apply only through approved workflow. +### Deletion protection + +Recommend for production databases, production branches, and other long-lived +branches where accidental deletion would be disruptive. If Terraform is the +source of truth, manage branch deletion protection with `deletion_protected` on +`planetscale_vitess_branch` and `planetscale_postgres_branch`; deleting a +protected Terraform-managed branch should be a reviewed two-step change that +first sets `deletion_protected = false` and applies before removing the +resource. + ## Vitess-specific recommendations ### Safe migrations @@ -77,6 +87,8 @@ Recommend for production branches and staging branches that accept deploy reques ### Deploy requests Recommend for schema changes into protected branches. +For active deploys, use deploy-request queue, operations, and deployment +inspection as evidence before changing strategy or throttler settings. ### Force cutover discipline diff --git a/13-autonomous-execution-mode/SKILL.md b/13-autonomous-execution-mode/SKILL.md index 73c10f4..773bec2 100644 --- a/13-autonomous-execution-mode/SKILL.md +++ b/13-autonomous-execution-mode/SKILL.md @@ -54,7 +54,8 @@ containing: recommendations; deploy with revert window; additive only (ADD INDEX, ADD COLUMN NULL)". Invalid: "keep the schema optimized". - Numeric bounds where applicable: max changes per run, max branch age - for deletion, budget modes permitted (warn only vs enforce). + for deletion, deletion-protection handling, budget modes permitted + (warn only vs enforce), and deploy-request throttler bounds. - Expiry date. Expired authorization = report-only mode. Recommended review interval: 90 days. @@ -78,7 +79,7 @@ Before the first mutation, produce and show an **execution plan**: 1. **Order by dependency, then by risk.** Prerequisites first (e.g. stop the app's boot-time DDL before enabling safe migrations, add an index before dropping the one it replaces). Among independent changes, lowest-risk first so early failures cost the least. 2. **Pre-flight each change.** Re-read the live state immediately before mutating (branch flags, recommendation state, webhook config). If the state no longer matches the report evidence, the change is **stale**: skip it, mark it `BLOCKED — state drift`, and continue with independent changes. -3. **Safety prerequisites are steps, not assumptions.** Before any Class D DDL: confirm a backup completed within the retention window, confirm safe migrations or a deploy request is the vehicle where the engine supports it, and prefer revertible mechanisms (deploy requests with revert window, warn-mode before enforce-mode for Traffic Control). +3. **Safety prerequisites are steps, not assumptions.** Before any Class D DDL: confirm a backup completed within the retention window, confirm safe migrations or a deploy request is the vehicle where the engine supports it, and prefer revertible mechanisms (deploy requests with revert window, warn-mode before enforce-mode for Traffic Control). Before any branch deletion, verify the branch is non-production, has no open deploy request, and is not deletion-protected unless the standing authorization explicitly names disabling protection. 4. **One atomic change at a time.** Never batch unrelated mutations into one command. Never parallelize Class D steps. 5. **Verify after each step.** Read the state back and confirm the expected effect before moving on. A change is not "done" when the command exits 0; it is done when the read-back matches the expected state. @@ -89,7 +90,7 @@ The operator handed over control; visibility is what they get in return. Emit st - **Plan announcement** — numbered steps, each with target, exact command/interface, expected effect, rollback mechanism, and class. This is the last thing shown before execution begins. - **Per-step, before**: `[step 3/7] STARTING VIT-3a — deploy request: add idx_orders_on_user_id to storefront-demo/main (Class D, revert window available)` - **Per-step, after**: `[step 3/7] DONE — deploy request #4 deployed, index visible in schema read-back (took 2m 10s)` -- **Long-running operations** (deploy requests, migrations, restores): poll and report progress at a sensible cadence, not just at completion. Include queue position/state transitions. +- **Long-running operations** (deploy requests, migrations, restores): poll and report progress at a sensible cadence, not just at completion. Include deploy request queue position, operations, deployment progress, throttler state, and other state transitions when available. - **Skips and blocks**: report immediately with the reason (`BLOCKED — state drift`, `EXCLUDED — Class E`, `SKIPPED — prerequisite failed`), never silently. - **Run summary** — the post-execution report from the change-gates skill: what changed, when, evidence of success, warnings, rollback state, follow-up monitoring. Plus the acknowledgment quote and the autonomy level used. @@ -107,6 +108,7 @@ Stop-the-line rules. When any of these fires, finish or safely abort the current 4. **State drift on a production target** (someone else changed it mid-run) → halt the run. 5. **Scope pressure** — anything needed that is outside the acknowledged scope → do not do it; report it. 6. **Error on a destructive step** → never auto-retry. Retries are permitted only for idempotent reads and transient network failures on non-destructive calls. +7. **Deletion protection blocks a destructive step** → halt that step. Do not disable protection unless the authorization explicitly names that target and action. After a halt: report state of every step (done / rolled back / blocked / not started), current database state, and what re-acknowledgment would be needed to resume. Never resume a halted run on the original acknowledgment. diff --git a/14-pscale-cli-automation/SKILL.md b/14-pscale-cli-automation/SKILL.md index 9e87157..f873138 100644 --- a/14-pscale-cli-automation/SKILL.md +++ b/14-pscale-cli-automation/SKILL.md @@ -50,6 +50,24 @@ browser; use `pscale auth login --format json`. sql … --force`). There is no global `--force` or `PSCALE_FORCE`. - **`--format json` alone never skips confirmations** — add `--force` on the destructive subcommand after explicit user approval. +- A failed delete may be an intentional safety signal from deletion protection. + Do not disable protection or retry with a destructive workflow unless the + operator explicitly approved that target and action. + +## Deploy request inspection + +For Vitess deploy request monitoring, these commands are read-only and suitable +for inventory or status reporting: + +```bash +pscale deploy-request queue --org --format json +pscale deploy-request operations --org --format json +pscale deploy-request deployment --org --format json +``` + +`pscale deploy-request throttler update --ratio ` +changes live throttling for that deploy request. Treat it as an approved +operational mutation, not as inspection. ## Typical workflow