🌐 PlanetScale CLI Skills

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

🎯 What This Skill Provides

• 18 sub-skills covering all major pscale commands
• 3 automation scripts for common workflows (create branch, deploy schema, sync)
• Decision trees for common questions (branch vs deploy request, tokens vs passwords)
• Troubleshooting sections for self-service problem solving
• Complete command reference in each sub-skill's references/ directory
• Token-efficient workflows (~90-95% reduction for repetitive operations)

📦 Installation

Agent Skills (npx skills)

This repository is a collection containing the planetscale-cli-skills orchestrator plus 18 standalone pscale-* skills. Each skill lives in its own directory with its own SKILL.md; there is intentionally no root SKILL.md so Agent Skills can discover every sibling instead of stopping at the repository root.

# List all discoverable skills without installing
npx skills add vince-winkintel/planetscale-cli-skills --list

# Interactive picker
npx skills add vince-winkintel/planetscale-cli-skills

# Install everything
npx skills add vince-winkintel/planetscale-cli-skills --all

# Install only selected skills
npx skills add vince-winkintel/planetscale-cli-skills \
  --skill planetscale-cli-skills \
  --skill pscale-import-d1

Via ClawHub

clawhub install planetscale-cli-skills

ClawHub releases preserve the existing full-collection install shape. Build the registry package from the release tag, copy planetscale-cli-skills/SKILL.md to package-root SKILL.md, remove the now-redundant nested orchestrator directory, and retain all standalone pscale-* skill directories. Do not publish the repository root directly or publish only planetscale-cli-skills/; either choice would break one of the supported discovery/install paths. The live listing remains on its last published version until the transformed package is published.

Via Git

git clone https://github.com/vince-winkintel/planetscale-cli-skills.git

🚀 Quick Start

Prerequisites

Install the PlanetScale CLI:

# macOS
brew install planetscale/tap/pscale

# Linux
wget https://github.com/planetscale/cli/releases/latest/download/pscale_X.X.X_linux_amd64.tar.gz
tar -xzf pscale_*.tar.gz
sudo mv pscale /usr/local/bin/

# Windows
scoop bucket add pscale https://github.com/planetscale/scoop-bucket.git
scoop install pscale

Automation scripts that parse pscale --format json output also require jq.

Authenticate

# Interactive login
pscale auth login

# Or use service tokens for CI/CD
export PLANETSCALE_SERVICE_TOKEN_ID=<token-id>
export PLANETSCALE_SERVICE_TOKEN=<token>

Create Your First Branch

# Using automation script
./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-branch

# Or manually
pscale branch create my-database feature-branch --from main

🧩 Sub-Skills

Skill	Use When	Common Commands
pscale-auth	Login, logout, authentication	pscale auth login/logout
pscale-branch	Create, restore to a PostgreSQL recovery point, rename, protect, diff, promote, and switchover branches; manage Postgres size/replicas/parameters/maintenance/extensions, resize Vitess VTGates, inspect branch infra, manage live routing rules, Lookup Vindexes, tablet throttling, query pattern reports, and Vitess MoveTables workflows	pscale branch create/update/switchover/diff/parameters/maintenance/extensions/resize/vtgate/infra/query-patterns/vtctld lookup-vindex
pscale-deploy-request	Deploy schema changes safely; inspect queues, operations, reviews, storage, and throttling; update auto-apply/auto-delete settings; unblock failed deploy/revert queues	pscale deploy-request create/deploy/update/unblock/queue/operations/storage-check/throttler
pscale-database	Manage settings, database-level Vitess throttler and aggressive-cutover defaults, PostgreSQL IP restrictions, shells, keyspaces, and read-only regions/dumps	pscale database show/update/throttler/aggressive-cutover/ip-restriction, pscale keyspace delete/read-only-regions, pscale shell
pscale-maintenance	Inspect Vitess Enterprise maintenance schedules and windows	pscale maintenance list/show/windows
pscale-sql	Non-interactive SQL for agents/scripts	pscale sql --query
pscale-metrics	Query historical/current branch metrics and engine-aware performance reports	pscale metrics show/instant/report
pscale-insights	Analyze production query performance, execution samples, tags, error details, anomaly correlations, and schema recommendations	pscale insights queries/tags/errors/errors show/anomalies/anomalies show/recommendations
pscale-traffic-control	Inventory and safely manage Postgres Traffic Control budgets and matching rules	pscale traffic-control budget list/show/create/update/delete, pscale traffic-control rule create/delete
pscale-inspect	Run point-in-time, read-only MySQL/Vitess and PostgreSQL diagnostics	pscale inspect all/locks/seq-scans/bloat
pscale-import-d1	Import Cloudflare D1 exports into PlanetScale Postgres	pscale import d1 lint/start/verify
pscale-backup	Create/restore backups and manage scheduled policies	pscale backup create/list/policy
pscale-billing	Inspect invoices and manage organization payment methods	pscale billing payment-method show/update/delete, pscale billing invoice list/show/line-items
pscale-audit-log	List audit events and export authentication attempts	pscale audit-log list/auth-attempts
pscale-password	Connection passwords and Postgres roles, including Vitess read-only-region credentials, named Postgres replica connection targets, status/expiration, and metadata/IP restriction updates	pscale password create/list/show/update, pscale role list/get/default
pscale-pgbouncer	Dedicated PostgreSQL PgBouncer lifecycle and asynchronous resizing	pscale pgbouncer list/show/create/resize/delete
pscale-org	Switch organizations, update settings, manage SSO/directory sync/domains, and inspect or manage members/teams	pscale org list/switch/update/sso/member/team
pscale-service-token	CI/CD authentication	pscale service-token create/show

🛠️ Automation Scripts

All scripts in scripts/ directory execute without loading into context (~90% token savings).

create-branch-for-mr.sh

Create PlanetScale branch matching your MR or PR:

./scripts/create-branch-for-mr.sh \
  --database my-database \
  --branch feature-schema-migration

deploy-schema-change.sh

Complete schema deployment workflow:

./scripts/deploy-schema-change.sh \
  --database my-database \
  --branch feature-schema-v2 \
  --deploy

sync-branch-with-main.sh

Create a replacement branch from the current base branch when production/base has changed:

./scripts/sync-branch-with-main.sh \
  --database my-db \
  --branch feature-branch \
  --new-branch feature-branch-rebased

🌊 Common Workflows

Schema Migration (Safe Production Deployment)

# 1. Create branch
pscale branch create my-db feature-schema --from main

# 2. Make schema changes
pscale shell my-db feature-schema
-- ALTER TABLE users ADD COLUMN last_login DATETIME;

# 3. View diff
pscale branch diff my-db feature-schema

# 4. Create deploy request
pscale deploy-request create my-db feature-schema

# 5. Deploy
pscale deploy-request deploy my-db 1

CI/CD Integration (GitHub Actions)

deploy-schema:
  steps:
    - name: Create branch
      run: |
        ./scripts/create-branch-for-mr.sh \
          --database ${{ secrets.DATABASE }} \
          --branch ${{ github.ref_name }}
    
    - name: Apply schema
      run: |
        pscale shell ${{ secrets.DATABASE }} ${{ github.ref_name }} < migrations.sql
    
    - name: Deploy
      run: |
        ./scripts/deploy-schema-change.sh \
          --database ${{ secrets.DATABASE }} \
          --branch ${{ github.ref_name }} \
          --deploy

Non-interactive SQL for agents/scripts

# Default role is reader; use JSON for machine-readable results
pscale sql my-db main --org my-org --format json --query "SELECT 1"

# Writes require an explicit write-capable role; destructive SQL also needs --force
# and should only be run after explicit user approval.
pscale sql my-db main --org my-org --role admin --query "UPDATE users SET disabled = true WHERE id = 123"

Database diagnostics

# Point-in-time, connection-level diagnostics (JSON combined report)
pscale inspect all my-db main --org my-org --format json

# Historical/current branch metrics and a curated engine-aware report
pscale metrics report my-db main --org my-org --period 1d --format json
pscale metrics show my-db main --org my-org --metric queries --metric latency_p99 --period 1h --format json

# Query-fingerprint analysis of production traffic
pscale insights queries my-db main --org my-org --sort p99Latency --period 1h --format json
pscale insights queries samples my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json
pscale insights tags summaries my-db main --org my-org --tags app --sort totalTime --format json
pscale insights errors my-db main --org my-org --period 1h --format json
pscale insights errors show my-db main <full-error-fingerprint> --org my-org --period 1h --format json
pscale insights anomalies show my-db main <anomaly-id> --org my-org --format json
pscale insights recommendations my-db --org my-org --format json
pscale insights recommendations show my-db <number> --org my-org --format json
pscale insights queries show my-db main <query-id> --org my-org --format json
pscale insights queries summary my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json
pscale insights queries traffic-budgets my-db main <fingerprint> --org my-org --keyspace <keyspace> --format json

# Inventory Postgres Traffic Control budgets and their rules
pscale traffic-control budget list my-db main --org my-org --format json

# Drill into specialized metrics for queries, tables, or tablets
pscale metrics queries my-db main --org my-org --metric latency_p99 --query-id <fingerprint-keyspace> --period 1h --format json
pscale metrics tables my-db main --org my-org --format json
pscale metrics tablets my-db main --org my-org --metric vreplication_lag --workflow <workflow> --period 1h --format json

pscale metrics provides historical/current branch telemetry, pscale insights provides query-fingerprint analysis, and pscale inspect provides live target-specific checks. For inspection, choose --dbname for PostgreSQL or --keyspace <keyspace>/<shard> for Vitess when defaults are not the intended target. Treat recommendation DDL as a proposal that still requires review and explicit approval.

Cloudflare D1 Import

# Export D1 with wrangler, then lint and dry-run before loading PlanetScale
pscale import d1 lint --input ./d1-export.sql --format json
pscale import d1 start my-db migration-branch --input ./d1-export.sql --dry-run --format json

# After reviewing the migration ID and warnings, run and verify the import
pscale import d1 start my-db migration-branch --input ./d1-export.sql --migration-id <id> --format json
pscale import d1 verify my-db migration-branch --migration-id <id> --input ./d1-export.sql --format json

Drizzle ORM Integration

# 1. Edit your schema file
vim schema.sql

# 2. Create PlanetScale branch and apply changes
./scripts/create-branch-for-mr.sh --database my-database --branch $(git branch --show-current)
pscale shell my-database $(git branch --show-current) < schema.sql

# 3. Deploy
./scripts/deploy-schema-change.sh --database my-database --branch $(git branch --show-current) --deploy

# 4. Pull schema back to Drizzle
pnpm drizzle-kit introspect

🎓 Decision Trees

Branch vs Deploy Request?

What's your goal?
├─ Experimenting → Create branch
├─ Testing changes → Create branch
├─ Ready for production → Create deploy request
└─ Review before prod → Deploy request (safe, reviewable)

Service Token vs Password?

Use case?
├─ CI/CD pipeline → Service token (rotatable, scoped)
├─ Local development → Password (temporary)
├─ Production app → Service token
└─ One-off admin → Password

Direct Promotion vs Deploy Request?

⚠️ Always use deploy requests for production

📊 Token Efficiency

Operation	Manual (7 steps)	Script (1 command)	Savings
Schema migration	~3000 tokens	~150 tokens	95%
Branch creation	~500 tokens	~50 tokens	90%
Deploy request	~800 tokens	~80 tokens	90%

🔗 Related Skills

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

📚 Resources

• PlanetScale CLI Docs
• PlanetScale GitHub
• ClawHub Page

🤝 Contributing

Contributions welcome! Please:

1. Follow existing skill structure patterns
2. Include decision trees and troubleshooting
3. Add scripts to scripts/ directory
4. Update README.md and relevant SKILL.md files

📄 License

MIT License - see LICENSE file.

🙏 Acknowledgments

• Built for OpenClaw AI agents
• Optimized using skill-creator patterns
• Inspired by gitlab-cli-skills