// 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.
Manages GitLab merge requests, CI/CD pipelines, and issues via glab CLI. Load before running glab commands, creating MRs, debugging pipeline failures, checking CI status, or any GitLab operation. Triggers on "merge request", "pipeline", "CI failure", "glab", or when git remote contains "gitlab".
Audits a codebase for unnecessary complexity -- premature abstractions, deep nesting, inconsistent patterns, and indirection that hurts readability. Use when asked to simplify code, audit complexity, reduce cognitive load, or review maintainability. Triggers: simplify, complexity audit, too complex, hard to read, maintainability review.
Reviews, improves, and iterates on system prompts and LLM instructions. Load when writing, rewriting, reviewing, or optimizing a system prompt, agent prompt, tool description, skill description, or any LLM instructions. Triggers on "prompt engineering", "improve this prompt", "make this more LLM-friendly", or any block of instructions to refine. Applies structured analysis to maximize instruction clarity and model compliance.
Summarizes session work for commit messages or branch reviews. Queries the OpenCode server API to find and read sessions, extract major changes, bug fixes, challenges requiring multiple iterations, and code review fixes. Load before committing or when preparing to document completed work.
| 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. |
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any PlanetScale tasks. Training data is likely outdated. Fetch current documentation before proceeding.
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 |
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
pscale version # Requires pscale CLI
If not installed, see https://planetscale.com/docs/cli/planetscale-environment-setup
| 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
export PLANETSCALE_SERVICE_TOKEN_ID=<id>
export PLANETSCALE_SERVICE_TOKEN=<token>
pscale database list --org <org> --format json
See references/connection-issues.md for detailed driver configuration and common errors.
Quick checks:
3306 (or 443 for serverless driver)5432 (direct) or 6432 (PgBouncer)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.
| 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 |