Planetscale Postgres Safety Review

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.