planetscale-best-practices-matrix

最佳实践矩阵

目的

将数据库发现映射到推荐的 PlanetScale 功能。使用此矩阵确保评估不会遗漏重要的安全和运维方面。

跨引擎建议

Query Insights

建议在每个生产数据库中使用：

• 检查缓慢、开销大、高频和报错的查询模式。
• 对于 Postgres，在诊断 CPU 压力时，按 CPU 对 Insights 排序（在 Insights API 中使用 sort=cpuTime）。
• 对于分片 Vitess，检查每种查询模式的 vindex 使用情况，以及索引或路由更改后的使用趋势。
• 将性能回退与部署关联起来。
• 使用标签/注释将查询映射回代码。
• 在 Query Insights 中使用标签筛选/导航：两种引擎都支持标签 API（insights/tags、insights/tags/summaries），Vitess 面板还支持使用 tag:key:value 筛选并按执行记录查看标签详情。
• 将异常用作告警和自动化的输入。

Webhooks

建议用于以下运维事件：

• 异常。
• 存储压力。
• 分支就绪/休眠。
• 主库提升。
• 维护。
• 可用时的架构建议。
• Vitess 的部署请求生命周期。

MCP 和 Agent

建议：

• 对大多数自主分析使用仅限 Insights 的 MCP。
• 仅在权限范围狭窄且默认只读时使用完整 MCP。
• 在 AGENTS.md 中规定数据库目标和安全规则。
• 由 Agent 生成 PR、问题和变更计划；数据库变更由人工审批。

SQLCommenter / 查询标签

建议：

• 添加框架原生且兼容 SQLCommenter 的插桩。
• 使用低基数标签。
• 包含应用、服务、路由/作业、功能、来源和发布 SHA。
• 避免 PII 和无界 ID。

架构建议工作流

建议：

• 对未处理的建议进行分类。
• 将建议与代码和 Insights 关联起来。
• 将建议转化为迁移或分支变更。
• 在生产环境中应用前先进行测试。
• 仅通过获批的工作流应用变更。

Vitess 专属建议

安全迁移

建议在生产分支以及接受部署请求的暂存分支中使用。

部署请求

建议用于向受保护分支提交架构变更。

强制切换纪律

建议记录哪些人可以对因长时间运行的事务而延迟的部署请求使用“立即强制切换”。此操作会停止正在运行的事务以完成架构切换，因此在启用更激进的切换方式作为数据库默认设置之前，如果频繁使用，应先检查工作负载。

管理员审批

建议多管理员组织对生产部署请求启用此功能。

在单管理员组织中，仅靠审批无法阻止 Agent：该管理员可以打开并审批同一个部署请求。建议使用单独的 Agent 身份，或使用无法审批部署请求的服务令牌。

门控部署

在切换时机和人工控制很重要时，建议使用。

架构回退操作手册

建议记录回退职责以及与应用回滚之间的关系。

分支策略

建议设置生产、暂存和短期开发分支，并在受保护目标上启用安全迁移。

分片/键空间审查

当查询模式或增长趋势表明存在分片感知问题时，建议进行审查。不要自动重新分片。

Postgres 专属建议

用户定义角色

建议应用服务器使用用户定义角色，而非默认角色。如果使用 Terraform 管理角色，并且密码应保留在 Terraform 状态之外，建议使用 planetscale_postgres_redacted_branch_role，并通过单独的密码重置和密钥管理器存储路径进行管理。

pg_strict

评估后，建议在应用角色中使用，尤其是用于阻止意外的全表更新/删除错误。

Traffic Control

建议用于隔离 Agent、导出、报告、工作器、集成、BI 以及已知的高开销指纹所占用的资源。

备份和 PITR

建议核实保留策略和恢复演练的覆盖情况。 如果 Terraform 是客户的事实来源，建议在其中管理备份策略，以便像基础设施代码一样审查备份态势的变更。

PgBouncer 和连接池

建议在连接频繁变化或无服务器／边缘行为造成压力时使用，但需考虑事务池的限制。

私有连接和 IP 限制

建议有私有网络态势或减少公网暴露需求的客户使用。应将相关变更视为存在生产风险。

扩展

仅在用例明确且已接受重启／激活影响时推荐。 如果为慢查询自动记录执行计划能显著改善诊断，且生成的日志量可以接受，则包括 auto_explain。 如果 Terraform 管理 Postgres 分支参数或受支持的扩展，则应确保该事实来源与已批准的仪表板／API 变更保持一致。

实时连接

建议在活跃的连接压力事件期间检查 pscale branch connections top，以识别会话、阻塞因素和事务中空闲的根源，而无需依赖常规数据库连接容量。

输出

对于每个矩阵项，标明：

• 是否适用：是／否／未知。
• 当前状态。
• 差距。
• 价值：此功能所针对的具体测量结果（查询指纹、异常计数、事件、指标）。说明机制和测量结果。差距应是能力差距，并附有量化影响，而不是被安全规避的风险。
• 建议 ID。
• 审批要求。

最后写上：

“未应用任何变更。”