Set up PlanetScale with an AI agent

name: planetscale
description: Use when managing relational databases (Vitess, Postgres, or Neki),
  creating branches for schema changes, deploying with zero downtime, monitoring
  query performance, managing backups, or automating database operations via CLI
  or API.
metadata:
  mintlify-proj: planetscale
  version: "1.0"

PlanetScale Skill

Product summary

PlanetScale is a fully-managed relational database platform offering three engines: Vitess (MySQL-compatible with unlimited horizontal sharding), Postgres (single-primary PostgreSQL), and Neki (Postgres with horizontal sharding). All run on locally-attached NVMe drives for unlimited IOPS and ultra-low latency.

Key files and commands:

• CLI: pscale (install via brew install pscale)
• API: https://api.planetscale.com/v1 (requires service token or OAuth)
• Authentication: Service tokens (for automation) or OAuth (for user-facing apps)
• Primary docs: https://planetscale.com/docs

When to use

Reach for this skill when:

• Creating or managing databases (Vitess, Postgres, or Neki)
• Making schema changes with zero downtime (branching + deploy requests)
• Monitoring query performance or investigating slow queries
• Creating backups, restoring data, or managing replicas
• Automating database operations via CLI or API
• Connecting applications to databases
• Scaling databases horizontally (Vitess or Neki)
• Importing data from external databases

Quick reference

CLI essentials

Task	Command
Authenticate	pscale auth login
Create database	pscale database create <db>
List databases	pscale database list --org <org>
Create branch	pscale branch create <db> <branch>
Connect to branch	pscale shell <db> <branch>
Execute SQL	pscale sql <db> <branch> --query "SELECT ..."
Create deploy request	pscale deploy-request create <db> <branch>
Deploy changes	pscale deploy-request deploy <db> <number>
Create backup	pscale backup create <db> <branch>
List backups	pscale backup list <db>
Create password	pscale password create <db> <branch>
View query insights	pscale insights queries <db> <branch>
Agent bootstrap	pscale agent-guide --format json

API authentication

Service token (automation):

curl -H "Authorization: Bearer <SERVICE_TOKEN>" \
  https://api.planetscale.com/v1/organizations

Service token ID + token (legacy):

curl -H "Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>" \
  https://api.planetscale.com/v1/organizations

Database engines

Engine	Use case	Key feature
Vitess	MySQL-compatible, massive scale	Unlimited horizontal sharding
Postgres	Standard PostgreSQL	Single primary, high availability
Neki	Postgres at scale	Horizontal sharding for Postgres

Connection types

Type	Use	Port
Primary	Write queries	3306 (MySQL) / 5432 (Postgres)
Replica	Read queries, auto-routes to nearest replica	3306 / 5432
Read-only region	Scoped to specific region	3306 / 5432

Decision guidance

When to use branching vs direct schema changes

Scenario	Approach	Why
Production database with safe migrations enabled	Create branch → make changes → deploy request	Zero downtime, reversible, team review
Development or testing branch	Direct schema changes on branch	Faster iteration, no deploy request needed
Large schema changes (>10 tables)	Split across multiple deploy requests	Single deploy request limited to 10 tables
Need to revert quickly	Use safe migrations + deploy request	30-minute revert window with data preservation

When to use Vitess vs Postgres vs Neki

Condition	Choice	Reason
MySQL-compatible workload, need sharding	Vitess	Battle-tested, unlimited sharding, proven at scale
PostgreSQL, single primary sufficient	Postgres	Native Postgres, simpler operations
PostgreSQL, need horizontal sharding	Neki	Postgres sharding without Vitess complexity
Unsure if you need sharding	Postgres or Neki	Start unsharded, upgrade later if needed
Data >250 GB and hitting limits	Vitess or Neki	Sharding becomes cost-effective

When to use CLI vs API

Task	CLI	API	Why
One-off operations	✅	❌	Faster to type
Automation/CI-CD	✅	✅	Both work; API more flexible
Programmatic database management	❌	✅	API designed for this
Local development	✅	❌	CLI is interactive
Webhooks/event-driven	❌	✅	API webhooks only

Workflow

Typical schema change workflow (Vitess/Postgres with branching)

1. Create a development branch off production:

   pscale branch create <database> <dev-branch>
   

2. Connect and make schema changes:

   pscale shell <database> <dev-branch>
   # Run DDL: CREATE TABLE, ALTER TABLE, etc.
   

3. Test changes locally in your application against the dev branch.

4. Create a deploy request to merge into production:

   pscale deploy-request create <database> <dev-branch>
   

5. Review the diff in the dashboard. Check for conflicts or issues.

6. Deploy when ready:

   pscale deploy-request deploy <database> <deploy-request-number>
   

7. Monitor the deployment in the dashboard. PlanetScale throttles automatically to avoid impact.

8. If issues arise, revert within 30 minutes (safe migrations enabled):

   pscale deploy-request revert <database> <deploy-request-number>
   

Typical backup and restore workflow

1. Create a backup:

   pscale backup create <database> <branch>
   

2. Poll until ready (backups take minutes):

   pscale backup show <database> <branch> <backup-id>
   

3. Restore to a new branch:

   pscale branch create <database> <new-branch> --restore <backup-id>
   

4. Verify data in the restored branch before deleting the original.

Typical API workflow (programmatic database creation)

1. Create a service token with create_database permission.

2. Create a database:

   curl -X POST https://api.planetscale.com/v1/organizations/<org>/databases \
     -H "Authorization: Bearer <SERVICE_TOKEN>" \
     -d '{"name":"my-db","engine":"vitess"}'
   

3. Poll until ready (databases take minutes):

   curl https://api.planetscale.com/v1/organizations/<org>/databases/<db> \
     -H "Authorization: Bearer <SERVICE_TOKEN>"
   

4. Create a password for the branch:

   curl -X POST https://api.planetscale.com/v1/organizations/<org>/databases/<db>/branches/main/passwords \
     -H "Authorization: Bearer <SERVICE_TOKEN>" \
     -d '{"name":"app-password"}'
   

Common gotchas

• Polling for resource readiness: Creating databases, branches, and backups returns immediately but resources aren't ready. Always poll until state: "ready" or ready: true before using.
• Service token permissions: Service tokens require explicit scopes. A token without create_database will fail silently. Check token permissions with pscale service-token show-access <token-id>.
• Deploy request limits: A single deploy request can only alter up to 10 tables. Split large migrations across multiple deploy requests.
• Safe migrations must be enabled: Without safe migrations on production, schema changes run directly and can lock tables. Enable in dashboard settings.
• Foreign key constraints: Foreign keys require explicit enablement in database settings. Disabling them simplifies some migrations but breaks referential integrity.
• Replica routing: Replica passwords auto-route to the nearest replica or read-only region. Don't use replica credentials for writes—they will fail.
• Connection pooling: Postgres uses PgBouncer (port 6432) for connection pooling. Direct connections (port 5432) bypass pooling. Use pooling for high-connection workloads.
• Vitess sharding complexity: Sharding requires careful vindex selection and query routing. Start with single-shard and migrate to sharding only when necessary.
• Postgres vs Vitess SQL differences: Vitess is MySQL-compatible, not Postgres-compatible. Migrating Postgres to Vitess requires SQL rewrites.
• Backup retention: Backups are retained per policy. Emergency backups have the same retention as manual backups. Deleting a branch does not delete its backups.
• API rate limits: The API has rate limits. Check X-RateLimit-* headers in responses. Implement exponential backoff for retries.
• Webhook delivery: Webhooks are not guaranteed to be delivered in order. Implement idempotency in webhook handlers.

Verification checklist

Before submitting work with PlanetScale:

• Database is ready: Polled the API/CLI until state: "ready" or ready: true
• Branch created successfully: Verified branch exists with pscale branch list <db>
• Schema changes tested: Ran changes on dev branch and tested locally
• Deploy request created: Used pscale deploy-request create or API
• No conflicts: Reviewed deploy request diff for schema conflicts
• Deployment successful: Monitored deployment in dashboard; no errors
• Revert window noted: If safe migrations enabled, noted 30-minute revert window
• Backups exist: Verified backup was created before major changes
• Connection strings correct: Tested connection with correct host/port/credentials
• Monitoring in place: Set up query insights or alerts for performance issues
• Service token scoped: Verified token has only required permissions (principle of least privilege)
• API polling implemented: For automation, implemented polling with exponential backoff

Resources

• Comprehensive page listing: https://planetscale.com/docs/llms.txt
• PlanetScale API reference: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api
• CLI reference: https://planetscale.com/docs/cli
• Vitess schema changes: https://planetscale.com/docs/vitess/schema-changes
• Postgres quickstart: https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart
• Neki overview: https://planetscale.com/docs/neki

---

For additional documentation and navigation, see: https://planetscale.com/docs/llms.txt