← Explore all skills

DATABASE REVIEW / PlanetScale

PlanetScale Postgres safety review

Reviews a PlanetScale Postgres database and recommends roles, pg_strict, backups, and Traffic Control without applying them.

“Review PlanetScale Postgres for Traffic Control, query tags, roles, pg_strict, backups/PITR, private connectivity, webhooks, branches, and safe agent operation.”

01 / THE REASONING

Why this made the selection.

  • The skill reviews PlanetScale Postgres for roles, pg_strict, backups, traffic control, and network posture, and it says not to apply changes.
  • Private connectivity is not treated as a public-access block, and schema changes stay in the application's migration workflow.

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-postgres-safety-review/SKILL.md
  • README.md
  • LICENSE

Our findings

  • The purpose section says to recommend practices and not to apply changes.
  • Branches, migrations, restores, role rotation, budgets, and network restrictions each have an explicit approval stop.
  • Private connectivity does not automatically block public access; IP restrictions are still required for a private-only posture.
  • The skill does not use Vitess deploy requests; schema changes are described as direct branch edits plus the app migration workflow.
  • The definition distinguishes Postgres direct branch migrations from Vitess deploy requests and treats query tags and raw invocation capture as complementary.

Not established by this review

  • The resource was not executed and its tools were not called.
  • 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.

Upstream setup instructions ↗

DOCUMENTED COMMAND

npx skills add planetscale/skills/planetscale-postgres-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-postgres-safety-review
  1. The command pins only this review skill at the reviewed commit. The installer was not executed.
  2. Do not use a global yes-to-all install of the repository. That would install skills this review did not select.
  3. For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/planetscale-planetscale-postgres-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.
  4. Place the extracted directory in your host's documented skills directory, named planetscale-postgres-safety-review. Keep SKILL.md and the licence together.

Before you start

  • Node.js and npm
  • A PlanetScale Postgres database you are allowed to read
  • The PlanetScale CLI (pscale), authenticated, which the README lists as a prerequisite

THE COMPLETE REVIEWED DEFINITION

Read it before you reuse it.

Original source bytes, with attribution.
Review the host-specific setup notes above.

---
name: planetscale-postgres-safety-review
description: Review PlanetScale Postgres for Traffic Control, query tags, roles, pg_strict, backups/PITR, private connectivity, webhooks, branches, and safe agent operation.
---

# Postgres safety review

## Purpose

Recommend best practices for a PlanetScale Postgres database. Focus on availability protection, application isolation, recovery, safe automation, and observability. Do not apply changes.

## Branch and schema workflow

PlanetScale Postgres branches do not use Vitess-style deploy requests. Schema changes are made directly to each branch, and production schema changes should be managed through the application’s normal migration workflow with a branch validation step.

Check:

- Whether a development or test branch exists.
- Whether branches are empty or restored from backup.
- Whether migrations are tested against a branch before production.
- Whether application migrations are reversible or have a documented rollback strategy.
- Whether production DDL is manually reviewed.

Recommend:

- Create or use a non-production branch for migration testing.
- Run migration validation and application tests against that branch.
- Treat production migration application as an explicit human-approved deployment step.
- Use PITR/backup restore branches for incident recovery, not as an automatic rollback mechanism.

Do not create branches, run migrations, or restore backups without approval.

## Roles and least privilege

Check whether the application connects with the default role. Flag this as a safety gap.

Recommend:

- Use user-defined application roles, not the default role, for application servers.
- Separate roles by service, environment, and access pattern.
- Use read-only roles for analytics, dashboards, reporting, and agents that do not need writes.
- Use short-lived or purpose-limited roles for automation.
- When Terraform manages PlanetScale Postgres roles, prefer
  `planetscale_postgres_redacted_branch_role` for roles whose password should
  stay out of Terraform state; reset the password through the API or dashboard
  and store it in the team's secret manager.
- Document credential rotation without application downtime.

Do not create, reset, delete, or rotate roles without approval.

## pg_strict

Check whether pg_strict is enabled for application roles.

Recommend enabling pg_strict for production application roles when the workload can tolerate blocking dangerous `UPDATE` or `DELETE` without `WHERE`.

Recommended rollout:

1. Enable warning mode or evaluate in non-production where possible.
2. Fix queries that would be blocked.
3. Enable strict blocking for application roles.
4. Document approved one-off override procedure.

Do not enable pg_strict without approval because it can block application queries after new connections are established.

## Query Insights and pginsights

Review:

- Slow queries.
- High rows-read queries.
- High CPU query patterns (`sort=cpuTime` or `sort=percentCpuTime` on the
  Insights API).
- High-frequency queries.
- Erroring queries.
- Active anomalies.
- Query tags.
- Whether literal/raw query collection is enabled.

Raw query collection is governed by the `pginsights.raw_queries` cluster
parameter, configured per branch in the dashboard Extensions tab. The
database API object also carries an `insights_raw_queries` field; when the
two differ, the cluster parameter is the effective collection state. Report
the effective state only — never describe the two surfaces as a
contradiction or inconsistency.

Recommend:

- Treat raw query collection as a capability, per
  `../planetscale-query-insights-and-tags/SKILL.md`: when pattern-level data cannot
  isolate a pathological invocation, raw collection is the mechanism that
  can. Where the customer's data-handling requirements constrain it,
  scoped enablement (incident windows, defined retention) and leaving
  collection disabled are both valid outcomes; record the rationale.
- Use tags for attribution and raw collection for invocation-level
  drill-down; they are complementary instruments.
- Use deploy SHA and route/job tags to correlate regressions with application deploys.

## Query tags

Evaluate whether SQL comments contain structured SQLCommenter tags.

Recommend tags that support both Insights and Traffic Control:

- `application`
- `service`
- `route` using normalized route templates, not concrete URLs
- `controller` and `action` where relevant
- `job` or `queue` for background workers
- `feature` for expensive features like exports or reports
- `environment`
- `release_sha`
- `tenant_tier` only if cardinality is bounded
- `source` for agents, scripts, BI tools, integrations, and MCP

Avoid high-cardinality or sensitive tags:

- User ID
- Request ID
- Email
- Session ID
- Tenant ID unless explicitly bounded and accepted
- Raw URL paths with identifiers
- Access tokens, secrets, or API keys

## Database Traffic Control

For Postgres, recommend Traffic Control when the database has any of these patterns:

- Public or customer-triggered expensive features.
- Exports, reports, analytics, or ad hoc search sharing the OLTP database.
- Background jobs that can starve interactive traffic.
- Third-party integrations with unpredictable query volume.
- Agent-generated queries.
- Known query fingerprints that occasionally run away.
- Tenant or route classes that need bounded database resource use.

Default recommendation:

- Start budgets in `warn` mode.
- Use query tags where possible.
- Use fingerprint-specific rules for known offenders.
- Use enforce mode only after observing warnings and confirming no critical traffic is blocked.
- Maintain an emergency disable procedure.

Do not create budgets or enforce rules without approval.

## Backups and PITR

Check:

- Automated backup schedule.
- Retention window.
- WAL/PITR availability.
- Manual backups that prevent deletion.
- Restore drill history.
- Recovery runbook.

Recommend:

- Confirm default backups meet the customer’s RPO/RTO.
- Increase retention or add backup schedules if the customer’s recovery window exceeds defaults.
- If Terraform is the customer's source of truth, manage backup policies in
  Terraform so retention and schedule changes are reviewed with the rest of
  the infrastructure code.
- Run a restore drill to a new branch.
- Document the exact application cutover procedure after restore.

Do not restore or create emergency backups without approval. Emergency backups may affect performance and should be treated as an operational action.

## Connections, pooling, and network safety

Check:

- Whether app uses direct port 5432 or PgBouncer port 6432.
- Whether connection pool size matches runtime and deployment model.
- Whether serverless or edge environments can create connection storms.
- Live connection/session pressure through `pscale branch connections top`,
  including blockers and idle-in-transaction sessions when diagnosing active
  incidents.
- Whether private connectivity is configured.
- Whether IP restrictions are configured.
- Whether public access remains available unexpectedly.

Recommend:

- Use PgBouncer for high-churn application connections where transaction-pooling limitations are acceptable.
- Use direct connections for session-dependent features that PgBouncer transaction mode cannot support.
- Use AWS PrivateLink or GCP Private Service Connect for private network requirements.
- Use IP restrictions to reduce public exposure.
- Be explicit that private connectivity does not automatically block public access; IP restrictions or equivalent controls are required for private-only posture.

Do not change network restrictions without approval. Network changes can break application connectivity.

## Extensions

Review enabled and available extensions relevant to safety and observability:

- `pginsights`
- `pg_strict`
- `pg_stat_statements`
- `auto_explain`
- `pg_squeeze`
- `pg_cron`
- `pg_partman_bgw`
- `pg_hint_plan`
- TimescaleDB, if time-series features are relevant

Recommend extensions only when use case is clear. `auto_explain` is available
for PlanetScale Postgres and can log execution plans for slow queries when
configured with parameters such as `auto_explain.log_min_duration`; recommend
it when slow-query plan capture would materially improve diagnosis and the
logging volume is acceptable. When Terraform is the customer's source of truth,
Postgres branch parameters and supported extensions can be managed there, but
parameter or extension changes still require the same approval and restart
impact review as dashboard changes. Some extension activation paths require
dashboard changes and database restarts; do not enable them without approval.

## Webhook recommendations for Postgres

Evaluate and recommend webhooks for:

- `branch.anomaly`
- `branch.out_of_memory`
- `branch.primary_promoted`
- `branch.ready`
- `branch.start_maintenance`
- `cluster.storage`
- `database.access_request`
- `branch.schema_recommendation` if available
- `webhook.test` for setup validation

Recommended automation behavior:

- Alerts: anomaly, out-of-memory, primary promotion, storage, maintenance.
- Agent intake: anomaly, schema recommendation.
- Human approval: any generated Traffic Control, schema, role, or network change.

## Output

Return:

- Current Postgres safety posture.
- Highest-risk availability gaps.
- Recommended Traffic Control plan.
- Recommended role and pg_strict plan.
- Recommended backup/PITR plan.
- Recommended network posture plan.
- Recommended query tagging plan.
- Proposed changes requiring approval.

End with:

“No Postgres 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 c0ade3da178c2a8d34e1b4c84e43ba56ffade3116eb020a63a8b1e7e74aeba7c

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.

  1. Skill definition ↗Checked

    https://github.com/planetscale/skills/blob/999045cfbad79222f38a99599eb96bc736feabee/planetscale-postgres-safety-review/SKILL.md

    Supports: summary, whySelected, limitations

  2. MIT licence ↗Checked

    https://github.com/planetscale/skills/blob/999045cfbad79222f38a99599eb96bc736feabee/LICENSE

    Supports: Redistribution terms

  3. https://raw.githubusercontent.com/planetscale/skills/999045cfbad79222f38a99599eb96bc736feabee/planetscale-postgres-safety-review/SKILL.md

    Supports: bestFor, review.notTested, review.reviewedAt

Evidence & Ask