tomevault-io 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(or443for serverless driver) - Postgres uses port
5432(direct) or6432(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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.