PlanetScale CLI Skills

PlanetScale CLI Skills

Comprehensive pscale command reference and workflows for managing PlanetScale databases via terminal.

Overview

The PlanetScale CLI brings database branches, deploy requests, and schema migrations to your fingertips. This skill provides command references, automation scripts, and decision trees for all pscale operations.

Configuration and credential safety

• Directory-local .pscale.yml files are project configuration, not trusted credential configuration. The CLI accepts only org, database, and branch from them and warns while ignoring keys such as API endpoints or tokens.
• Keep API URLs and credentials in the user config, environment/secret manager, or explicit approved flags. Never commit them to a repository-local config.
• pscale api follows cross-host redirects without forwarding authentication or caller-supplied headers. Even with this protection, pass secret-bearing headers only to an explicitly verified API host and do not expose them in logs.
• When --format json is active, API error codes are preserved in the top-level code field instead of being collapsed to COMMAND_FAILED. Branch automation should branch on exact codes when present; for schema_mutation_blocked, wait for the active vtctld mutation or deploy to finish before retrying.

Sub-Skills

Decision Trees

Should I use a branch or deploy request?

What's your goal?
├─ Experimenting with schema changes → Create branch (pscale-branch)
├─ Testing schema in isolation → Create branch (pscale-branch)
├─ Ready to deploy schema to production → Create deploy request (pscale-deploy-request)
└─ Reviewing schema changes before production → Review deploy request (pscale-deploy-request)

Service token vs password?

What's your use case?
├─ CI/CD pipeline → Service token (pscale-service-token)
├─ Local development → Password (pscale-password)
├─ Production application → Service token (rotatable, secure)
└─ One-off admin task → Password (temporary)

Direct promotion vs deploy request?

Production readiness?
├─ Immediate promotion (dangerous) → pscale branch promote (pscale-branch)
├─ Review + approval workflow → pscale deploy-request create (pscale-deploy-request)
└─ Safe production deployment → Always use deploy requests

Common Workflows

Schema Migration Workflow

Complete workflow from branch creation to production deployment:

# 1. Create development branch
pscale branch create  

# 2. Make schema changes (via shell, ORM, or direct SQL)
pscale shell  

# 3. View schema diff
pscale branch diff  

# 4. Create deploy request
pscale deploy-request create  

# 5. Review and deploy
pscale deploy-request deploy  

# 6. Verify deployment
pscale deploy-request show  

See scripts/ directory for automation.

Branch Development Workflow

# Create branch from main
pscale branch create   --from main

# Work on schema changes
pscale shell  

# Check diff before deploying
pscale branch diff  

# Create deploy request when ready
pscale deploy-request create  

CI/CD Integration

# Create service token for CI/CD
pscale service-token create --org 

# Use in CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
export PLANETSCALE_SERVICE_TOKEN_ID=
export PLANETSCALE_SERVICE_TOKEN=

# Create and deploy via CI/CD after review/approval gates pass
pscale deploy-request create   --format json
pscale deploy-request deploy  

Cloudflare D1 to PlanetScale Postgres import

# Lint and dry-run first; review the JSON migration ID and warnings
pscale import d1 lint --input ./d1-export.sql --format json
pscale import d1 start   --input ./d1-export.sql --dry-run --format json

# After explicit confirmation, run and verify the import
pscale import d1 start   --input ./d1-export.sql --migration-id  --format json
pscale import d1 verify   --migration-id  --input ./d1-export.sql --format json

Quick Reference

Most Common Commands

# Authentication
pscale auth login
pscale auth logout

# Branch management
pscale branch create   [--from ]
pscale branch list 
pscale branch delete  
pscale branch parameters list   --format json
pscale branch resize status   --format json
pscale branch vtgate show   --format json

# Discover and use a Vitess read-only region
pscale keyspace read-only-regions    --format json
pscale password create    --read-only-region  --format json

# Deploy requests
pscale deploy-request create  
pscale deploy-request list 
pscale deploy-request deploy  

# Database operations
pscale database create  --org 
pscale database list
pscale shell  

# Non-interactive read query for agents/scripts
pscale sql   --org  --format json --query "SELECT 1"

# Point-in-time diagnostics plus server-side production-traffic analysis
pscale inspect all   --org  --format json
pscale insights queries   --org  --sort p99Latency --period 1h --format json
pscale insights recommendations  --org  --format json

# Cloudflare D1 import dry-run
pscale import d1 start   --input ./d1-export.sql --dry-run --format json

Related Skills

• drizzle-kit - ORM schema management and migrations
• gitlab-cli-skills - GitLab MR workflow integration
• github - GitHub PR and CI/CD integration

Automation Scripts

See scripts/ directory for token-efficient automation:

• create-branch-for-mr.sh - Create PlanetScale branch matching your MR/PR branch name
• deploy-schema-change.sh - Complete schema migration workflow
• sync-branch-with-main.sh - Create a replacement branch from main/base for conflict resolution

Scripts execute without loading into context (~90% token savings).

Resources

• Official docs: https://planetscale.com/docs/reference/planetscale-cli
• GitHub: https://github.com/planetscale/cli
• Community: https://github.com/planetscale/discussion