{"name":"planetscale-best-practices-matrix","url":"https://skills.sh/planetscale/skills/planetscale-best-practices-matrix","install":"npx skills add planetscale/skills --skill planetscale-best-practices-matrix","sdk":"planetscale","key":"planetscale/planetscale-best-practices-matrix","description":"A concise feature matrix for deciding which PlanetScale safety, observability, and automation recommendations apply by engine.","hasContent":true,"content":"---\nname: planetscale-best-practices-matrix\ndescription: A concise feature matrix for deciding which PlanetScale safety, observability, and automation recommendations apply by engine.\n---\n\n# Best-practices matrix\n\n## Purpose\n\nMap database findings to recommended PlanetScale features. Use this to ensure the assessment does not miss major safety and operational surfaces.\n\n## Cross-engine recommendations\n\n### Query Insights\n\nRecommend for every production database:\n\n- Review slow, expensive, high-frequency, and erroring query patterns.\n- For Postgres, sort Insights by CPU (`sort=cpuTime` on the Insights API)\n  when diagnosing CPU pressure.\n- For sharded Vitess, review vindex usage per query pattern and the usage\n  trend after index or routing changes.\n- Correlate regressions with deploys.\n- Use tags/comments to map queries back to code.\n- Use tag filtering/navigation in Query Insights: the tags API\n  (`insights/tags`, `insights/tags/summaries`) on both engines, plus\n  `tag:key:value` filtering and per-execution tag drill-down in the Vitess\n  dashboard.\n- Use anomalies as alert and automation inputs.\n\n### Webhooks\n\nRecommend for operational events:\n\n- Anomalies.\n- Storage pressure.\n- Branch readiness/sleeping.\n- Primary promotion.\n- Maintenance.\n- Schema recommendations where available.\n- Deploy request lifecycle for Vitess.\n\n### MCP and agents\n\nRecommend:\n\n- Use insights-only MCP for most autonomous analysis.\n- Use full MCP only with narrow scopes and read-only default.\n- Put database targeting and safety rules in `AGENTS.md`.\n- Agents generate PRs/issues/change plans; humans approve database changes.\n\n### SQLCommenter / query tags\n\nRecommend:\n\n- Add framework-native SQLCommenter-compatible instrumentation.\n- Use low-cardinality tags.\n- Include application, service, route/job, feature, source, and release SHA.\n- Avoid PII and unbounded IDs.\n\n### Schema recommendation workflow\n\nRecommend:\n\n- Triage open recommendations.\n- Correlate with code and Insights.\n- Convert into migrations or branch changes.\n- Test before production.\n- Apply only through approved workflow.\n\n## Vitess-specific recommendations\n\n### Safe migrations\n\nRecommend for production branches and staging branches that accept deploy requests.\n\n### Deploy requests\n\nRecommend for schema changes into protected branches.\n\n### Force cutover discipline\n\nRecommend documenting who may use \"force cutover now\" for deploy requests\ndelayed by long-running transactions. It stops running transactions to finish\nschema cutover, so frequent use should trigger workload review before enabling\naggressive cutover as the database default.\n\n### Admin approval\n\nRecommend for production deploy requests in multi-admin organizations.\n\nIn a single-admin organization, approval alone is not a guard against agents: that admin can\nopen and approve the same deploy request. Prefer a separate agent identity, or a service token\nthat cannot approve deploy requests.\n\n### Gated deployments\n\nRecommend when cutover timing and human control matter.\n\n### Schema revert runbook\n\nRecommend documenting revert responsibilities and the application rollback relationship.\n\n### Branch strategy\n\nRecommend production, staging, and short-lived development branches with safe migrations on protected targets.\n\n### Sharding/keyspace review\n\nRecommend when query patterns or growth suggest shard-awareness problems. Do not reshard automatically.\n\n## Postgres-specific recommendations\n\n### User-defined roles\n\nRecommend for application servers instead of default role. If roles are managed\nby Terraform and passwords should stay outside Terraform state, prefer\n`planetscale_postgres_redacted_branch_role` plus a separate password reset and\nsecret-manager storage path.\n\n### pg_strict\n\nRecommend for application roles after evaluation, especially to block accidental full-table update/delete mistakes.\n\n### Traffic Control\n\nRecommend for resource isolation of agents, exports, reports, workers, integrations, BI, and known expensive fingerprints.\n\n### Backups and PITR\n\nRecommend verifying retention and restore drill coverage.\nIf Terraform is the customer's source of truth, recommend managing backup\npolicies there so backup posture changes are reviewed as infrastructure code.\n\n### PgBouncer and connection pooling\n\nRecommend where connection churn or serverless/edge behavior creates pressure, subject to transaction-pooling limitations.\n\n### Private connectivity and IP restrictions\n\nRecommend for customers requiring private network posture or reduced public exposure. Treat changes as production-risking.\n\n### Extensions\n\nRecommend only when use case is clear and restart/activation impact is accepted.\nInclude `auto_explain` when automatic plan logging for slow queries would\nmaterially improve diagnosis and the resulting log volume is acceptable.\nIf Terraform manages Postgres branch parameters or supported extensions, keep\nthat source of truth aligned with approved dashboard/API changes.\n\n### Live connections\n\nRecommend inspecting `pscale branch connections top` during active connection\npressure incidents to identify sessions, blockers, and idle-in-transaction\nroots without relying on normal database connection capacity.\n\n## Output\n\nFor each matrix item, mark:\n\n- Applies: yes/no/unknown.\n- Current state.\n- Gap.\n- Value: the specific measured finding this feature addresses (query\n  fingerprint, anomaly count, incident, metric). State the mechanism and\n  the measurement. Gaps are capability gaps with quantified impact, not\n  risks safely avoided.\n- Recommendation ID.\n- Approval requirement.\n\nEnd with:\n\n“No changes have been applied.”\n","contentSource":"skills.sh/api/download/planetscale/skills/planetscale-best-practices-matrix","contentFetchedAt":"2026-07-27T08:59:28.318Z"}