Agent Skills: PlanetScale

PlanetScale

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any PlanetScale tasks. Training data is likely outdated. Fetch current documentation before proceeding.

Documentation Index

Fetch from https://planetscale.com/docs first.

| Category | Path | Use for | |----------|------|---------| | Docs index | https://planetscale.com/llms.txt | Full docs sitemap for discovery | | Vitess (MySQL) | /docs/vitess | MySQL-compatible databases, branching, deploy requests, sharding | | Postgres | /docs/postgres | PostgreSQL databases, roles, PgBouncer | | Postgres extensions | /docs/postgres/extensions | pg_stat_statements, pgvector, PostGIS, etc. | | CLI reference | /docs/cli | All pscale commands and flags | | API reference | /docs/api/reference | REST API, service tokens, OAuth | | Query Insights (Vitess) | /docs/vitess/monitoring/query-insights | Slow query analysis for Vitess | | Query Insights (Postgres) | /docs/postgres/monitoring/query-insights | Slow query analysis for Postgres | | Schema recommendations | /docs/vitess/monitoring/schema-recommendations | Index and schema optimization | | Connections (Vitess) | /docs/vitess/connecting/connection-strings | MySQL connection strings, passwords | | Connections (Postgres) | /docs/postgres/connecting | Postgres roles, PgBouncer, connection pooling |

FIRST: Check for MCP Server

If the PlanetScale MCP server is available, prefer it over CLI for querying databases and insights:

| Tool | Use for | |------|---------| | planetscale_execute_read_query | SELECT, SHOW, DESCRIBE, EXPLAIN queries | | planetscale_execute_write_query | INSERT, UPDATE, DELETE (prompts for DDL) | | planetscale_get_insights | Query performance data for a branch | | planetscale_get_branch_schema | Schema for a branch | | planetscale_list_databases | List databases in an org | | planetscale_list_branches | List branches in a database | | planetscale_search_documentation | Search PlanetScale docs |

MCP setup: https://planetscale.com/docs/connect/mcp

Verify CLI Installation

pscale version  # Requires pscale CLI

If not installed, see https://planetscale.com/docs/cli/planetscale-environment-setup

Quick Reference: pscale CLI

| Task | Command | |------|---------| | Authenticate | pscale auth login | | List databases | pscale database list | | Open MySQL shell | pscale shell <db> <branch> | | Create branch | pscale branch create <db> <branch> | | Create deploy request | pscale deploy-request create <db> <branch> | | Deploy changes | pscale deploy-request deploy <db> <number> | | Create password/role | pscale password create <db> <branch> <name> (Vitess) / pscale role create <db> <branch> <name> (Postgres) |

Use pscale <command> --help for subcommands and flags. Full CLI reference: https://planetscale.com/docs/cli

Service token auth (CI/CD)

export PLANETSCALE_SERVICE_TOKEN_ID=<id>
export PLANETSCALE_SERVICE_TOKEN=<token>
pscale database list --org <org> --format json

Connection Troubleshooting

See references/connection-issues.md for detailed driver configuration and common errors.

Quick checks:

• Vitess uses port 3306 (or 443 for serverless driver)
• Postgres uses port 5432 (direct) or 6432 (PgBouncer)
• All connections require SSL/TLS
• Passwords are branch-specific and cannot be recovered after creation

Query Insights via CLI

Use pscale api to query the Insights API (authenticates automatically):

# Create a query patterns report
pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports" --method POST

# Check report status
pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports/{id}/status"

# Download completed report
pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports/{id}"

Look for queries with high rows_read / rows_returned ratio (missing index) or high total_time_s (optimization target). See references/api-queries.md for analysis guidance.

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | Access denied for user | Invalid credentials or wrong branch | Verify password matches branch; create new password | | certificate verify failed | Missing/wrong SSL config | Use sslmode=require or system CA certs | | too many connections | Connection limit exceeded | Use connection pooling; check max_connections | | target: X.-.primary: not found | Branch doesn't exist or wrong keyspace | Verify branch name; check keyspace in connection | | FATAL: sorry, too many clients | Postgres connection limit | Use PgBouncer on port 6432 | | remaining connection slots reserved | Postgres at max_connections | Reduce direct connections; use pooling |