pscale-branch - SKILL.md Agent Skill

name: pscale-branch description: Create, delete, promote, diff, and manage PlanetScale database branches. Use when creating development branches for schema changes, viewing schema diffs, promoting branches to production, or managing branch lifecycle. Essential for schema migration workflows. Triggers on branch, create branch, schema diff, promote branch, development branch, database branch.

pscale branch

Create, delete, diff, and manage database branches.

Common Commands

# Create branch from main
pscale branch create <database> <branch-name>

# Create branch from specific source
pscale branch create <database> <branch-name> --from <source-branch>

# List all branches
pscale branch list <database>

# Show branch details
pscale branch show <database> <branch-name>

# View schema diff
pscale branch diff <database> <branch-name>

# View schema
pscale branch schema <database> <branch-name>

# Delete branch
pscale branch delete <database> <branch-name>

# Promote to production
pscale branch promote <database> <branch-name>

Workflows

Schema Migration Workflow (Standard)

# 1. Create development branch
pscale branch create my-database feature-migration --from main

# 2. Make schema changes (via shell, ORM, or direct SQL)
pscale shell my-database feature-migration
# ... run ALTER TABLE, CREATE TABLE, etc.

# 3. View changes
pscale branch diff my-database feature-migration

# 4. Create deploy request (safer than direct promotion)
pscale deploy-request create my-database feature-migration

# 5. Deploy via deploy request (see pscale-deploy-request)

Quick Branch for MR/PR

# Match PlanetScale branch to your MR/PR branch
BRANCH_NAME="feature-add-user-preferences"
pscale branch create my-database $BRANCH_NAME --from main

See scripts/create-branch-for-mr.sh for automation.

Schema Comparison

# Compare branch schema with main
pscale branch diff <database> <branch-name>

# View full branch schema
pscale branch schema <database> <branch-name>

# Export schema to file
pscale branch schema <database> <branch-name> > schema.sql

Branch Cleanup

# List all branches
pscale branch list <database>

# Delete merged/stale branches
pscale branch delete <database> <old-branch-name>

Decision Trees

Should I promote directly or use deploy request?

What's your environment?
├─ Production database → ALWAYS use deploy request (safe, reviewable)
├─ Pre-production database with team → Use deploy request (review workflow)
├─ Personal dev database → Direct promotion OK (but deploy request still safer)
└─ Experimental changes → Keep as branch, don't promote

When to create a new branch?

What's your goal?
├─ Schema migration for feature → Create branch (from main)
├─ Testing schema changes → Create branch (isolated)
├─ Hotfix schema change → Create branch (from production)
├─ Experiment / spike → Create branch (delete after)
└─ Working on existing schema → Use existing branch

Troubleshooting

"Branch already exists"

Solution:

# Check existing branches
pscale branch list <database>

# Use different name or delete existing
pscale branch delete <database> <existing-branch>

Schema diff shows no changes

Causes:

No schema changes made yet
Changes not committed in database session
Comparing branch to itself

Solution:

# Verify schema was modified
pscale branch schema <database> <branch-name>

# Ensure you're in the right branch when making changes
pscale shell <database> <branch-name>

Cannot delete branch

Error: "Branch is protected" or "Branch is a production branch"

Solution:

# Demote production branch first
pscale branch demote <database> <branch-name>

# Then delete
pscale branch delete <database> <branch-name>

Branch creation fails

Common causes:

Invalid branch name (spaces, special chars)
Source branch doesn't exist
Insufficient permissions

Solution:

# Use valid branch name (alphanumeric, hyphens, underscores)
pscale branch create <database> my-feature-branch --from main

# Verify source branch exists
pscale branch list <database> | grep main

Related Skills

pscale-deploy-request - Create deploy requests from branches (safer than direct promotion)
pscale-database - Database management
drizzle-kit - ORM-based schema migrations (generates SQL for pscale shell)
gitlab-cli-skills - MR/PR integration (match branch names across tools)

References

See references/commands.md for complete pscale branch command reference.

Branch Lifecycle

main (production)
  │
  ├─ Create branch ──> feature-branch (development)
  │                         │
  │                         ├─ Make schema changes
  │                         ├─ Test changes
  │                         └─ Create deploy request
  │                               │
  └─ Deploy ←──────────────────────┘

Best Practices

Always create branches from main for schema changes
Use descriptive branch names matching MR/PR numbers when applicable
Run diff before deploy request to review changes
Delete merged branches to keep branch list clean
Use deploy requests instead of direct promotion (reviewable, revertable)
Test schema changes in branch before deploying