PlanetScale Best Practices: A Production DB Checklist

The most important PlanetScale Best Practices distinction is that the Vitess workflow and Postgres development workflow are different. Write the engine, production branch, migration process and recovery owner into the runbook before launch. A branch name alone does not tell you which schema or connection rules apply.

This checklist covers Vitess/MySQL and standard PlanetScale Postgres, using official documentation checked on October 6, 2026. It does not extend these instructions to Neki’s separate sharded-Postgres workflow. The operational advice is to verify each item on the deployed database and application rather than rely on a feature being present somewhere in the platform.

1. Give each engine the right branch workflow

Vitess development branches normally provide isolated copies of the production schema for testing. Data Branching is a separate option that includes schema and data. Production branches are intended for production traffic, and safe migrations can enforce a branch/deploy-request workflow. Vitess workflow.

New Postgres branches are empty unless restored from a backup. Initialize them with your schema migrations and seed scripts. Branches do not automatically synchronize schema changes, and new branches start with default configuration, so extensions and custom parameters need to be re-enabled. Postgres development environments and compatibility.

My checklist is to validate the branch’s schema, representative test data, extension configuration and credentials before a test starts. Delete disposable branches when the work ends. A test against an empty database may confirm SQL syntax while telling you little about production query behavior.

2. Separate safe schema deployment from application compatibility

For Vitess, enable safe migrations on production. It rejects direct DDL and requires changes through branches and deploy requests. The online workflow creates a ghost table and synchronizes data before applying the change. When schema revert is enabled, the retained old table supports a 30-minute revert window. Safe migrations.

The checklist for a Vitess change is:

• Create the development branch and apply the desired schema there.
• Review the deploy request’s DDL and schema diff with the application change.
• Confirm sufficient disk headroom for the operation.
• Deploy and inspect the relevant query patterns immediately.
• Know whether schema revert is enabled and who owns the revert decision.

The workflow and system-limits docs describe the schema diff, conflict checks and disk requirements. They do not prove that old application code works with a new column type. Vitess workflow and disk limits.

For Postgres, test the migration in an isolated branch and apply it using your standard migration process. PlanetScale recommends schema-before-code ordering when adding a column, and code-before-schema ordering when removing a feature and its table. There is no automatic branch schema sync. Postgres development workflow.

For live Postgres index builds, consider CREATE INDEX CONCURRENTLY after testing the migration tooling. It avoids locks that block writes but performs more work, cannot run inside a transaction block, and can leave an invalid index if the build fails. Inspect the result rather than assuming an exited migration means a usable index. PostgreSQL CREATE INDEX.

3. Choose connection paths deliberately

For Postgres OLTP, PlanetScale recommends PgBouncer where compatible. Local PgBouncer uses port 6432; direct Postgres uses 5432. PlanetScale-managed PgBouncers use transaction pooling. Schema changes, pg_dump, session-specific features and other long-running operations belong on direct connections. Local PgBouncer routes to the primary; use a dedicated replica bouncer for pooled replica traffic. PgBouncer guide.

The Postgres resilience guide recommends dedicated PgBouncers for demanding production OLTP. It also recommends recycling all connections within 24 hours, keeping transactions under three seconds for cleaner failovers, and retrying transient read failures. Write retries need verification that the original did not complete or an idempotent operation. Connection resilience.

Record maximum application instances, pool size per instance, pool checkout timeout, connect timeout and query timeout. Check the deployed PgBouncer server-pool configuration across every bouncer; limits are not removed by placing a pooler in front of Postgres. Use the connection exhaustion guide when the origin refuses new sessions.

For Vitess, the documented simultaneous transaction pool depends on instance size. Shorten transactions or reduce parallelism before treating exhaustion as a reason to upgrade. Client connections held beyond 24 hours may also be terminated. Vitess system limits.

4. Record current limits in the runbook

These are the current documented Vitess limits, not Postgres limits or universal service guarantees. PlanetScale notes that some limits can be adjusted per database through support. Vitess system limits.

Paginate large reads and bound backfills. The docs warn that result-size limits can be reached before the row count when rows contain large values, and that near-full disks can prevent deploy-request operations. Network-attached Vitess storage auto-scales up to 4 TB; Metal disk options depend on compute and must be planned separately. Vitess limits and recommendations.

For Postgres, inspect the deployed parameters and PgBouncer configuration instead of importing the table above. PlanetScale documents manual CPU/RAM sizing and configurable connection-pool settings. Storage autoscaling applies to network-attached clusters. Postgres compatibility and PgBouncer configuration.

5. Validate constraints and indexes against your workload

Do not repeat the old claim that PlanetScale never supports foreign keys. Vitess foreign-key constraint support can be enabled per database and is currently documented for unsharded environments. A deploy request adding a foreign key does not validate existing row relationships, so orphaned data may remain. Certain reverts can also produce orphaned rows. Vitess foreign-key documentation.

Postgres supports native foreign keys, triggers and stored procedures; extensions are restricted to PlanetScale’s supported list, and there is no customer SUPERUSER access. Check required extensions and version compatibility before importing a workload. Postgres compatibility.

On Vitess, schema recommendations can suggest indexes from production telemetry. Traffic-dependent recommendations run daily and are generated for the default branch. The docs recommend benchmarking on a non-production branch and verifying the result in Insights. Adding indexes has memory/storage costs; redundant indexes also affect writes. Schema recommendations.

My review requirement is simple: every index change names the query pattern it helps, the existing indexes it overlaps and the measurement that will establish success. The Insights guide walks through a Postgres example without promising an invented speedup.

6. Use Insights and capacity telemetry together

Inspect expensive patterns by total time, count, tail latency and rows read, scoped to the correct branch and server. Postgres Insights includes CPU and block-cache statistics, with I/O timing dependent on track_io_timing. Postgres Query Insights.

Export infrastructure metrics into the system that alerts your team. PlanetScale’s Postgres Prometheus guide documents branch discovery and metrics for connections, PgBouncer, WAL and CPU; it requires read_metrics_endpoints on a service token. Prometheus integration.

My launch checks would cover connection pressure, slow-query regression, application error rate, disk headroom and missing telemetry. Test the notification route, not only the chart. If an agent is collecting evidence, start with the insights-only official MCP endpoint; it excludes both SQL execution tools. The PlanetScale MCP guide explains setup and permission scopes. Official MCP docs.

7. Rehearse backups and recovery before the first incident

Vitess Base includes automatic backups every 12 hours, with manual and additional scheduled backups available. Restoration creates a new branch, and additional scheduled backups have a storage charge. Vitess backups.

Postgres includes automatic backups every 12 hours on development and production branches, with two-day default retention. WAL-based PITR allows restoration between the oldest backup and five minutes before the current time. Restored branches stay in the source region; extensions must be reinstalled, and restored user-role passwords are reset. Extended retention and additional backup storage can cost more. Postgres backup and restore.

Write a recovery drill that restores to a new branch, configures the required extensions, obtains the restored credentials and exercises the application against it. Decide how to account for writes after the selected recovery point before switching traffic. A new branch containing data is only one step in recovering the service.

A production-ready handoff

Before launch, attach the engine-specific migration procedure, tested connection budget, current limits, query baseline and timed restore drill to the service runbook. Include who can approve a schema change and who owns the recovery decision.

The PlanetScale platform page and integration setup describe connecting PlanetScale to Polylane, so it can see when a database breaks. Polylane integration documentation.

Running on PlanetScale? See how Polylane monitors PlanetScale in production.