planetscale

name	planetscale
description	Manages PlanetScale databases via MCP server or pscale CLI. Load before running pscale commands, using PlanetScale MCP tools, debugging connection errors, or analyzing slow queries.

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 read-only MCP discovery and query tools 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

Safety Rules

• Never run write queries, DDL, deploy requests, branch deletion, password/role changes, or production-impacting actions without explicit confirmation.
• Discover org, database, branch, engine type (Vitess vs Postgres), and environment before giving connection or migration advice.
• Prefer read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN) for diagnosis.
• Do not print secrets or connection strings with passwords.

Verify CLI Installation

pscale version  # Requires pscale CLI

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

Discovery Workflow

1. Check whether MCP tools are available; use them first for read-only introspection.
2. If using CLI, verify pscale version and auth.
3. List or confirm org, database, branch, and engine.
4. Fetch current docs for the relevant Vitess/Postgres/API/CLI topic.
5. Run read-only diagnostics before recommending mutations.

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