planetscale-vitess-safety-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vitess safety review

Vitess 安全性评审

Purpose

目的

Recommend best practices for a PlanetScale Vitess database. Focus on production safety, deployability, observability, and agent-safe automation. Do not apply any changes.

为PlanetScale Vitess数据库推荐最佳实践。重点关注生产环境安全性、可部署性、可观测性以及Agent安全自动化。请勿执行任何变更。

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.

检查生产分支和预发布分支是否已启用安全迁移。

在以下场景建议启用安全迁移：

该分支承载生产流量。
团队在部署请求之外执行DDL操作。
无受保护分支工作流。
应用预期会频繁变更Schema。

说明权衡点：安全迁移会拒绝受保护分支上的直接DDL操作，强制通过部署请求进行Schema变更。这是一项功能，但可能会打破依赖直接生产环境DDL操作的团队工作流程。启用该功能属于会改变团队行为的变更，需要获得批准。

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变更。
是否需要管理员审批。
是否针对数据丢失、冲突、语法检查错误、外键问题、字符集问题以及分片影响对部署请求进行评审。
团队是否使用 gated deployments（ gated 部署）来控制切换时机。
是否使用“立即部署”功能，以及团队是否了解该功能会移除 gated 部署/回滚机制。
切换操作是否经常因长时间运行的事务而延迟。
是否通过Webhook订阅部署请求事件。

建议：

生产环境Schema变更必须使用部署请求。
当存在多名管理员时，生产环境部署请求需启用管理员审批。
在单管理员组织中，管理员审批无法阻止以该管理员身份运行的Agent：发起部署请求的管理员也可以审批请求。如果目标是防止Agent自审批，应为Agent创建单独用户，或使用不具备部署请求审批权限的服务令牌。
除非确认迁移是即时安全且回滚方案可接受，否则优先选择常规安全部署而非即时部署。
当切换时机很重要时，使用gated部署。
将“立即强制切换”视为针对延迟切换的操作员可控操作：它会强制终止运行中的事务以完成Schema切换。建议在使用前检查阻塞工作负载和事件背景，仅当频繁切换阻塞的情况已被理解并接受时，才推荐使用数据库级的强制切换默认设置。

Schema revert

Schema回滚

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.

检查团队是否了解回滚窗口，以及他们的事件运行手册是否包含回滚流程。

建议记录：

如何识别有问题的Schema迁移。
如何在支持的窗口内执行回滚。
谁有权执行回滚。
Schema回滚时应同时回滚哪个应用版本。

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.

推荐分支拓扑：

启用安全迁移的
```
main
```
或等效生产分支。
基于生产分支创建并启用安全迁移的
```
staging
```
分支。
基于预发布分支创建的短期开发分支。
从开发分支向预发布分支发起部署请求，在合适时再从预发布分支向生产分支发起请求。

未经批准不得创建分支。

Query Insights

查询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.

评审Insights中的以下内容：

慢查询。
读取过多行的查询。
报错的查询。
索引使用不佳的查询。
对于分片数据库，查询模式是否使用相关的vindex，以及索引或路由变更后vindex的使用情况如何变化。
异常的查询量。
缺失的SQL注释标签。
当存在内置元数据或SQLCommenter标签时的标签细分：仪表盘中的
```
tag:key:value
```
过滤，以及用于程序化细分的
```
insights/tags
```
和
```
insights/tags/summaries
```
API端点。
部署关联数据。

建议启用或优化应用查询标签，以便Insights能够将查询归因到应用、路由、控制器、操作、任务、部署SHA以及功能模块。

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.

评审当前和近期的异常情况。

建议：

将
```
branch.anomaly
```
Webhook订阅到团队的告警或自动化系统。
将异常负载路由到会审工作流，以创建问题或Agent任务。
将异常情况与部署请求、应用部署以及查询标签相关联。
不要自动根据异常事件应用Schema或代码变更；仅生成提案或PR。

Schema recommendations

Schema建议

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.

评审未处理的Schema建议。

针对每个建议，记录：

类型：添加索引、移除冗余索引、主键耗尽、未使用表、遗留字符集/排序规则或其他类型。
受影响的表和keyspace。
支持的查询遥测数据。
DDL语句。
预期收益。
风险。
测试方案。

建议实施路径：

将建议转换为应用迁移或PlanetScale分支Schema变更。
创建部署请求。
评审生成的DDL和分片影响。
在分支上进行基准测试或验证。
通过安全迁移进行部署。
部署后监控Insights和异常状态。

请勿直接应用建议。

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.

检查备份状态和恢复运行手册。

建议：

确认自动备份已存在。
定期执行非生产环境恢复演练。
记录恢复目标、RPO/RTO预期以及应用切换方案。
对于分片数据库，记录分片感知的恢复预期。

Sharding and keyspace safety

分片与Keyspace安全性

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.

如果数据库已分片，评审：

Keyspace和分片。
Vschema。
跨分片查询模式。
Schema部署请求是否显示每个分片的影响。
查询是否使用分片友好的访问路径。

仅作为提案推荐Agent安全的分片评审。切勿自动执行重分片、修改vschema或变更路由操作。

Webhook recommendations for Vitess

Vitess的Webhook建议

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.

评估并推荐以下Webhook：

```
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
```
若客户数据库的Webhook API支持，还包括
```
branch.schema_recommendation
```

推荐的目标地址：

异常情况、主节点提升、存储以及部署错误的告警系统。
部署请求生命周期的Slack或内部通知系统。
Schema建议和异常情况的Agent接收队列，默认仅输出PR。

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.”

当前Vitess安全状态。
缺失的安全特性。
推荐的工作流。
推荐的Webhook订阅。
Schema建议会审表。
部署安全缺口。
需要批准的拟议变更。

结尾需包含：

“No Vitess changes have been applied.”