DATABASE REVIEW / PlanetScale
PlanetScale Vitess safety review
Review a PlanetScale Vitess database and recommend safety posture. The skill's own first instruction is not to apply changes.
“Review a PlanetScale Vitess database for safe migrations, deploy requests, schema recommendations, Insights, webhooks, and operational safety.”
01 / THE REASONING
Why this made the selection.
- The file is a review that recommends posture and says not to apply changes.
- Deploy requests, revert windows, and backups are separate checks rather than one flag.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- planetscale-vitess-safety-review/SKILL.md
- LICENSE
Our findings
- The pinned skill reviews safe migrations, deploy requests, schema revert, branch topology, Query Insights, anomalies, schema recommendations, backups, and sharding.
- It recommends safe migrations on branches that receive production traffic or that accept DDL outside deploy requests.
- Webhook recommendations are limited to branch.anomaly, branch.primary_promoted, and branch.ready.
- The output is current posture, missing features, and a recommended workflow, not a schema change.
- The source identifies the single-admin self-approval case and recommends a distinct agent identity or token without approval permission.
Not established by this review
- The skill was not executed inside a host agent.
- Not executed: it was not installed or run.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills add planetscale/skills/planetscale-vitess-safety-review Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.
Optional: install the reviewed revision
Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.
npx skills add https://github.com/planetscale/skills/tree/999045cfbad79222f38a99599eb96bc736feabee/planetscale-vitess-safety-review - The command pins only this review skill at the reviewed commit. The installer was not executed.
- Do not use a global yes-to-all install of the repository. That would install skills this review did not select.
- For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/planetscale-vitess-safety-review/bundle.zip and extract it into a new directory. It holds SKILL.md unchanged at revision 999045cf, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named planetscale-vitess-safety-review. Keep SKILL.md and the licence together.
Before you start
- Node.js and npm
- A PlanetScale Vitess database you are allowed to read
THE COMPLETE REVIEWED DEFINITION
Read it before you reuse it.
Original source bytes, with attribution.
Review the host-specific setup notes above.
---
name: planetscale-vitess-safety-review
description: Review a PlanetScale Vitess database for safe migrations, deploy requests, schema recommendations, Insights, webhooks, and operational safety.
---
# Vitess safety review
## Purpose
Recommend best practices for a PlanetScale Vitess database. Focus on production safety, deployability, observability, and agent-safe automation. Do not apply any changes.
## Primary safety features to evaluate
### Safe migrations
Check whether safe migrations are enabled on production and staging branches.
Recommend enabling safe migrations when:
- The branch receives production traffic.
- The team runs DDL outside deploy requests.
- There is no protected branch workflow.
- The application is expected to evolve schema frequently.
Explain the tradeoff: safe migrations reject direct DDL on protected branches and force schema changes through deploy requests. That is a feature, but it can break teams relying on direct production DDL. Treat enablement as a behavior-changing change requiring approval.
### Deploy requests
Check:
- Whether deploy requests are used for schema changes.
- Whether administrator approval is required.
- Whether deploy requests are reviewed for data loss, conflicts, lint errors, foreign key problems, charset issues, and shard impact.
- 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 deploy request events are subscribed to via webhooks.
Recommend:
- Require deploy requests for production schema changes.
- Enable administrator approval for production deploy requests when there is more than one administrator.
- In a single-admin organization, administrator approval does not stop an agent that acts as that admin:
the admin who opens a deploy request can also approve it. If the goal is to keep agents from
self-approving, give the agent a separate user, or a service token without deploy request
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.
- 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
before use, and only recommend the database-level aggressive cutover default
when frequent cutover blocking is understood and accepted.
### Schema revert
Check whether the team knows the revert window and whether their incident runbook includes it.
Recommend documenting:
- How to identify a bad schema migration.
- How to revert within the supported window.
- Who is authorized to revert.
- Which application deploy should be rolled back together with the schema revert.
### Branch strategy
Recommend a branch topology:
- `main` or equivalent production branch with safe migrations enabled.
- `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.
Do not create branches without approval.
### Query Insights
Review Insights for:
- Slow queries.
- Queries reading too many rows.
- Erroring queries.
- Queries with poor index usage.
- For sharded databases, whether query patterns use relevant vindexes and how
vindex usage changes after index or routing changes.
- Unusual query volume.
- Missing SQL comment tags.
- Tag breakdowns when built-in metadata or SQLCommenter tags are present:
`tag:key:value` filtering in the dashboard, and the `insights/tags` and
`insights/tags/summaries` API endpoints for programmatic breakdowns.
- Deploy correlation data.
Recommend enabling or improving application query tagging so Insights can attribute queries to app, route, controller, action, job, deployment SHA, and feature.
### Anomalies
Review active and recent anomalies.
Recommend:
- Subscribe `branch.anomaly` webhooks to the team’s alerting or automation system.
- Route anomaly payloads to a triage workflow that opens an issue or agent task.
- Correlate anomalies with deploy requests, application deploys, and query tags.
- Do not automatically apply schema or code changes from anomaly events; generate a proposal or PR only.
### Schema recommendations
Review open schema recommendations.
For each recommendation, capture:
- Type: add index, remove redundant index, primary key exhaustion, unused table, legacy charset/collation, or other.
- Affected table and keyspace.
- Supporting query telemetry.
- DDL.
- Expected benefit.
- Risk.
- Test plan.
Recommend implementation path:
- Convert the recommendation into an application migration or PlanetScale branch schema change.
- Open a deploy request.
- Review generated DDL and shard impact.
- Benchmark or validate on a branch.
- Deploy with safe migrations.
- Monitor Insights and anomaly state after deployment.
Do not apply recommendations directly.
### Backups and restore
Check backup posture and restore runbooks.
Recommend:
- Verify automated backups exist.
- Run a non-production restore drill periodically.
- Document restore target, RPO/RTO expectation, and application cutover plan.
- For sharded databases, document shard-aware restore expectations.
### Sharding and keyspace safety
If the database is sharded, review:
- Keyspaces and shards.
- Vschema.
- Cross-shard query patterns.
- Whether schema deploy requests show per-shard impact.
- Whether queries use shard-friendly access paths.
Recommend an agent-safe sharding review only as a proposal. Never reshard, change vschema, or alter routing automatically.
## Webhook recommendations for Vitess
Evaluate and recommend webhooks for:
- `branch.anomaly`
- `branch.primary_promoted`
- `branch.ready`
- `branch.sleeping`
- `cluster.storage`
- `keyspace.storage`
- `deploy_request.opened`
- `deploy_request.queued`
- `deploy_request.in_progress`
- `deploy_request.pending_cutover`
- `deploy_request.schema_applied`
- `deploy_request.errored`
- `deploy_request.reverted`
- `deploy_request.closed`
- `branch.schema_recommendation` if available in the webhook API for the customer’s database
Recommended destinations:
- Alerting for anomaly, primary promotion, storage, and deploy errors.
- Slack or internal notifications for deploy request lifecycle.
- Agent intake queue for schema recommendations and anomalies, with PR-only output by default.
## Output
Return:
- Current Vitess safety posture.
- Missing safety features.
- Recommended workflow.
- Recommended webhook subscriptions.
- Schema recommendation triage table.
- Deploy safety gaps.
- Proposed changes requiring approval.
End with:
“No Vitess changes have been applied.”
The download contains SKILL.md. Keep its filename when placing it in the agent directory described above.
By PlanetScale. Exact upstream source ↗ · Licence · Attribution
SHA-256 c60a3fd1f2fda2822e0a02481ef5204ec53efd53a65de0166da5036e259f57fc
Read the applicable licence
MIT License Copyright (c) 2026 PlanetScale Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
- Vitess safety review skill ↗Checked
https://github.com/planetscale/skills/blob/999045cfbad79222f38a99599eb96bc736feabee/planetscale-vitess-safety-review/SKILL.md
Supports: Review-only scope, Approval gates for schema and cutover actions
- MIT licence ↗Checked
https://github.com/planetscale/skills/blob/999045cfbad79222f38a99599eb96bc736feabee/LICENSE
Supports: Copyright (c) 2026 PlanetScale, Redistribution with attribution
https://raw.githubusercontent.com/planetscale/skills/999045cfbad79222f38a99599eb96bc736feabee/planetscale-vitess-safety-review/SKILL.md
Supports: bestFor, review.notTested, review.reviewedAt