Back to Details

planetscale-best-practices-matrix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Best-practices matrix

最佳实践矩阵

Purpose

用途

Map database findings to recommended PlanetScale features. Use this to ensure the assessment does not miss major safety and operational surfaces.
将数据库检测结果映射到推荐的PlanetScale功能。使用此矩阵可确保评估不会遗漏主要的安全和运维层面。

Cross-engine recommendations

跨引擎建议

Query Insights

Query Insights

Recommend for every production database:
  • Review slow, expensive, high-frequency, and erroring query patterns.
  • For Postgres, sort Insights by CPU (
    sort=cpuTime
    on the Insights API) when diagnosing CPU pressure.
  • For sharded Vitess, review vindex usage per query pattern and the usage trend after index or routing changes.
  • Correlate regressions with deploys.
  • Use tags/comments to map queries back to code.
  • Use tag filtering/navigation in Query Insights: the tags API (
    insights/tags
    , 
    insights/tags/summaries
    ) on both engines, plus 
    tag:key:value
    filtering and per-execution tag drill-down in the Vitess dashboard.
  • Use anomalies as alert and automation inputs.
为所有生产数据库推荐：
  • 审查慢查询、高成本查询、高频查询和出错的查询模式。
  • 对于Postgres，诊断CPU压力时，按CPU对Insights排序（在Insights API上使用
    sort=cpuTime
    ）。
  • 对于分片Vitess，审查每个查询模式的vindex使用情况，以及索引或路由变更后的使用趋势。
  • 将性能退化与部署关联起来。
  • 使用标签/注释将查询映射回代码。
  • 在Query Insights中使用标签过滤/导航：两个引擎均支持标签API（
    insights/tags
    、
    insights/tags/summaries
    ），此外Vitess控制台还支持
    tag:key:value
    过滤和按执行标签钻取详情。
  • 将异常作为告警和自动化的输入。

Webhooks

Webhooks

Recommend for operational events:
  • Anomalies.
  • Storage pressure.
  • Branch readiness/sleeping.
  • Primary promotion.
  • Maintenance.
  • Schema recommendations where available.
  • Deploy request lifecycle for Vitess.
为运维事件推荐：
  • 异常情况。
  • 存储压力。
  • 分支就绪/休眠状态。
  • 主节点提升。
  • 维护操作。
  • 可用的Schema建议。
  • Vitess的部署请求生命周期。

MCP and agents

MCP与代理

Recommend:
  • Use insights-only MCP for most autonomous analysis.
  • Use full MCP only with narrow scopes and read-only default.
  • Put database targeting and safety rules in 
    AGENTS.md
    .
  • Agents generate PRs/issues/change plans; humans approve database changes.
推荐：
  • 大多数自主分析使用仅Insights的MCP。
  • 仅在窄范围且默认只读的情况下使用完整MCP。
  • 将数据库目标和安全规则放在
    AGENTS.md
    中。
  • 代理生成PR/问题/变更计划；由人工批准数据库变更。

SQLCommenter / query tags

SQLCommenter / 查询标签

Recommend:
  • Add framework-native SQLCommenter-compatible instrumentation.
  • Use low-cardinality tags.
  • Include application, service, route/job, feature, source, and release SHA.
  • Avoid PII and unbounded IDs.
推荐：
  • 添加框架原生的SQLCommenter兼容埋点。
  • 使用低基数标签。
  • 包含应用程序、服务、路由/任务、功能、来源和版本SHA。
  • 避免包含PII（个人可识别信息）和无界ID。

Schema recommendation workflow

Schema推荐流程

Recommend:
  • Triage open recommendations.
  • Correlate with code and Insights.
  • Convert into migrations or branch changes.
  • Test before production.
  • Apply only through approved workflow.
推荐：
  • 分类处理未处理的推荐项。
  • 与代码和Insights关联起来。
  • 转换为迁移或分支变更。
  • 上线前测试。
  • 仅通过批准的流程应用变更。

Vitess-specific recommendations

Vitess专属建议

Safe migrations

安全迁移

Recommend for production branches and staging branches that accept deploy requests.
为接受部署请求的生产分支和 staging 分支推荐。

Deploy requests

部署请求

Recommend for schema changes into protected branches.
为向受保护分支进行Schema变更推荐。

Force cutover discipline

强制切换规范

Recommend documenting who may use "force cutover now" for deploy requests delayed by long-running transactions. It stops running transactions to finish schema cutover, so frequent use should trigger workload review before enabling aggressive cutover as the database default.
建议记录谁可以对因长事务延迟的部署请求使用“立即强制切换”。此操作会终止运行中的事务以完成Schema切换，因此频繁使用时，应先审查工作负载，再将激进切换设为数据库默认值。

Admin approval

管理员审批

Recommend for production deploy requests in multi-admin organizations.
In a single-admin organization, approval alone is not a guard against agents: that admin can open and approve the same deploy request. Prefer a separate agent identity, or a service token that cannot approve deploy requests.
为多管理员组织的生产部署请求推荐。
在单管理员组织中，仅审批无法防范代理：该管理员可以发起并批准同一个部署请求。建议使用单独的代理身份，或无法批准部署请求的服务令牌。

Gated deployments

Gated部署

Recommend when cutover timing and human control matter.
当切换时机和人工控制很重要时推荐。

Schema revert runbook

Schema回滚手册

Recommend documenting revert responsibilities and the application rollback relationship.
建议记录回滚职责以及与应用程序回滚的关联关系。

Branch strategy

分支策略

Recommend production, staging, and short-lived development branches with safe migrations on protected targets.
推荐生产分支、staging分支和短期开发分支，并在受保护目标上启用安全迁移。

Sharding/keyspace review

分片/键空间审查

Recommend when query patterns or growth suggest shard-awareness problems. Do not reshard automatically.
当查询模式或增长表明存在分片感知问题时推荐。不要自动重新分片。

Postgres-specific recommendations

Postgres专属建议

User-defined roles

用户定义角色

Recommend for application servers instead of default role. If roles are managed by Terraform and passwords should stay outside Terraform state, prefer 
planetscale_postgres_redacted_branch_role
plus a separate password reset and secret-manager storage path.
为应用服务器推荐使用用户定义角色而非默认角色。如果角色由Terraform管理，且密码不应存放在Terraform状态中，建议优先使用
planetscale_postgres_redacted_branch_role
，并搭配单独的密码重置和密钥管理器存储路径。

pg_strict

pg_strict

Recommend for application roles after evaluation, especially to block accidental full-table update/delete mistakes.
评估后为应用角色推荐，尤其用于阻止意外的全表更新/删除错误。

Traffic Control

流量控制

Recommend for resource isolation of agents, exports, reports, workers, integrations, BI, and known expensive fingerprints.
为代理、导出、报告、工作器、集成、BI和已知的高成本查询指纹推荐资源隔离。

Backups and PITR

备份与PITR

Recommend verifying retention and restore drill coverage. If Terraform is the customer's source of truth, recommend managing backup policies there so backup posture changes are reviewed as infrastructure code.
建议验证保留期限和恢复演练覆盖范围。 如果Terraform是客户的事实数据源，建议在其中管理备份策略，以便备份状态变更作为基础设施代码被审查。

PgBouncer and connection pooling

PgBouncer与连接池

Recommend where connection churn or serverless/edge behavior creates pressure, subject to transaction-pooling limitations.
当连接频繁波动或无服务器/边缘行为造成压力时推荐，需注意事务池的限制。

Private connectivity and IP restrictions

私有连接与IP限制

Recommend for customers requiring private network posture or reduced public exposure. Treat changes as production-risking.
为需要私有网络状态或减少公网暴露的客户推荐。将此类变更视为具有生产风险的操作。

Extensions

扩展

Recommend only when use case is clear and restart/activation impact is accepted. Include 
auto_explain
when automatic plan logging for slow queries would materially improve diagnosis and the resulting log volume is acceptable. If Terraform manages Postgres branch parameters or supported extensions, keep that source of truth aligned with approved dashboard/API changes.
仅当用例明确且接受重启/激活影响时推荐。 如果自动记录慢查询执行计划能显著提升诊断效果，且日志量在可接受范围内，建议包含
auto_explain
。 如果Terraform管理Postgres分支参数或支持的扩展，需确保该事实数据源与已批准的控制台/API变更保持一致。

Live connections

实时连接

Recommend inspecting 
pscale branch connections top
during active connection pressure incidents to identify sessions, blockers, and idle-in-transaction roots without relying on normal database connection capacity.
建议在连接压力事件期间查看
pscale branch connections top
，以识别会话、阻塞器和事务中空闲的根源，而无需依赖正常的数据库连接容量。

Output

输出

For each matrix item, mark:
  • Applies: yes/no/unknown.
  • Current state.
  • Gap.
  • Value: the specific measured finding this feature addresses (query fingerprint, anomaly count, incident, metric). State the mechanism and the measurement. Gaps are capability gaps with quantified impact, not risks safely avoided.
  • Recommendation ID.
  • Approval requirement.
End with:
“No changes have been applied.”
对于矩阵中的每个条目，标记：
  • 适用：是/否/未知。
  • 当前状态。
  • 差距。
  • 价值：该功能解决的具体可衡量检测结果（查询指纹、异常数量、事件、指标）。说明机制和衡量标准。差距是具有量化影响的能力差距，而非可安全规避的风险。
  • 推荐ID。
  • 审批要求。
结尾标注：
“未应用任何变更。”