> pscale

the PlanetScale CLI — branch databases like code, ship schema changes through deploy requests, and manage MySQL & Postgres from the terminal

setup & auth databases & regions branches connect & shell passwords & credentials postgres roles & traffic deploy requests backups & data sharding & workflows automation & ci

// setup & auth

8 commands

Install the PlanetScale CLI

$ brew install planetscale/tap/pscale

$ pscale auth login

Check whether you're authenticated

$ pscale auth check

Log out and revoke the session

$ pscale auth logout

List and inspect your organizations

$ pscale org list

Switch the active organization

$ pscale org switch my-org

Run one command against another org

$ pscale database list --org other-org

Set up shell completion

$ pscale completion zsh > "${fpath[1]}/_pscale"

// databases & regions

8 commands

Create a MySQL database

$ pscale database create mydb --region us-east

Create a Postgres database

$ pscale database create mydb --engine postgresql --region gcp-asia-northeast3 --replicas 2

List all databases in your org

$ pscale database list

Inspect a database or open it in the browser

$ pscale database show mydb

Delete a database

$ pscale database delete mydb

List available regions

$ pscale region list

Find the lowest-latency region from your machine

$ pscale ping

List available cluster sizes

$ pscale size cluster list

// branches

14 commands

Create a development branch

$ pscale branch create mydb add-users-table

Branch from another branch

$ pscale branch create mydb add-users-index --from add-users-table

Create a branch with production data

$ pscale branch create mydb test-migration --seed-data

Script branch creation and wait until ready

$ pscale branch create mydb ci-check-$GITHUB_RUN_ID --wait

List all branches of a database

$ pscale branch list mydb

Show branch details

$ pscale branch show mydb add-users-table

View the schema of a branch

$ pscale branch schema mydb add-users-table

Diff a branch against its parent

$ pscale branch diff mydb add-users-table

Lint a branch's schema for errors

$ pscale branch lint mydb add-users-table

Promote a branch to production

$ pscale branch promote mydb main

Demote a production branch to development

$ pscale branch demote mydb old-prod

Enable safe migrations on a production branch

$ pscale branch safe-migrations enable mydb main

Delete a branch

$ pscale branch delete mydb add-users-table

Pin your project to a branch

$ pscale branch switch add-users-table --database mydb

// connect & shell

9 commands

Open a SQL shell to a branch

$ pscale shell mydb main

Open a read-only shell

$ pscale shell mydb main --role reader

Tunnel a branch to localhost

$ pscale connect mydb add-users-table

Tunnel on a specific port

$ pscale connect mydb add-users-table --port 3309

Launch your app with an injected DATABASE_URL

$ pscale connect mydb dev-branch --execute 'pnpm dev'

Watch live connection activity

$ pscale branch connections top mydb main

List connections and queries on a branch

$ pscale branch connections show mydb main --format json

Kill a runaway query or connection

$ pscale branch connections kill mydb main <query-id> --query

Kill a stuck Postgres transaction

$ pscale branch connections kill-transaction mydb main <transaction-id>

// passwords & credentials

6 commands

Create a branch password for your app

$ pscale password create mydb main my-app-prod

Create a read-only password

$ pscale password create mydb main metabase-ro --role reader

Create a password that expires

$ pscale password create mydb main debug-session --ttl 2h

List branch passwords

$ pscale password list mydb main

Delete a branch password

$ pscale password delete mydb main <password-id>

Renew an expiring branch password

$ pscale password renew mydb main <password-id>

// postgres roles & traffic

9 commands

Create a role for a Postgres branch

$ pscale role create mydb main analytics-ro --inherited-roles pg_read_all_data

Create an admin role

$ pscale role create mydb main migration-admin --inherited-roles postgres

Create a temporary role with a TTL

$ pscale role create mydb main hotfix-debug --inherited-roles pg_read_all_data --ttl 1h

List roles on a Postgres branch

$ pscale role list mydb main

Reset a role's password

$ pscale role reset mydb main <role-id>

Reset the default postgres role credentials

$ pscale role reset-default mydb main

Delete a role and reassign what it owns

$ pscale role reassign mydb main <role-id> --successor app-rw

Cap query load with a traffic budget

$ pscale traffic-control budget create mydb main --name batch-jobs --capacity 2000 --rate 20 --mode warn

Match queries to a traffic budget with rules

$ pscale traffic-control rule create mydb main <budget-id> --fingerprint 'select * from analytics_events where ...'

// deploy requests

11 commands

Open a deploy request for schema changes

$ pscale deploy-request create mydb add-users-table

Target a specific base branch

$ pscale deploy-request create mydb add-users-table --into staging

List deploy requests

$ pscale deploy-request list mydb

Show a deploy request's status

$ pscale deploy-request show mydb 12

Review the schema diff of a deploy request

$ pscale deploy-request diff mydb 12

Approve or comment on a deploy request

$ pscale deploy-request review mydb 12 --approve

Deploy the schema change

$ pscale deploy-request deploy mydb 12

Deploy instantly with ALGORITHM=INSTANT

$ pscale deploy-request deploy mydb 12 --instant

Gate the schema swap for manual confirmation

$ pscale deploy-request create mydb risky-change --disable-auto-apply

Revert a deployed schema change

$ pscale deploy-request revert mydb 12

Cancel or close a deploy request

$ pscale deploy-request cancel mydb 12

// backups & data

7 commands

Create a manual backup

$ pscale backup create mydb main --name pre-users-migration

List backups of a branch

$ pscale backup list mydb main

Restore a backup to a new branch

$ pscale backup restore mydb recovery-branch <backup-id>

Delete a backup

$ pscale backup delete mydb main <backup-id>

Dump a database to local files

$ pscale database dump mydb main --output ./dump

Dump only specific tables or schema

$ pscale database dump mydb main --tables users,orders --output ./dump

Restore a local dump into a branch

$ pscale database restore-dump mydb import-branch --dir ./dump

// sharding & workflows

9 commands

List keyspaces in a branch

$ pscale keyspace list mydb main

Create a sharded keyspace

$ pscale keyspace create mydb main sharded-ks --shards 2 --cluster-size PS-40 --wait

Resize a keyspace's cluster

$ pscale keyspace resize mydb main my-keyspace --cluster-size PS-80

Show or update the VSchema

$ pscale keyspace vschema show mydb main sharded-ks

Move tables to another keyspace

$ pscale workflow create mydb main --name move-events --source-keyspace mydb --target-keyspace sharded-ks --tables events,event_properties

Monitor a running workflow

$ pscale workflow list mydb main

Verify data consistency before cutover

$ pscale workflow verify-data mydb main 1

Switch traffic to the target keyspace

$ pscale workflow switch-traffic mydb main 1 --replicas-only

Complete or abandon the table migration

$ pscale workflow cutover mydb main 1

// automation & ci

10 commands

Create a service token

$ pscale service-token create --name deploy-pipeline

Grant a service token database access

$ pscale service-token add-access <token-id> create_branch read_branch delete_branch --database mydb

Audit and revoke service token access

$ pscale service-token list

Authenticate CI with a service token

$ export PLANETSCALE_SERVICE_TOKEN_ID=<token-id> PLANETSCALE_SERVICE_TOKEN=<token-secret>

Get machine-readable output from any command

$ pscale branch list mydb --format json | jq -r '.[].name'

Call the PlanetScale API directly

$ pscale api organizations/{org}/databases

POST to the API with fields

$ pscale api organizations/{org}/databases -F 'name="scratch-db"'

Create a webhook for database events

$ pscale webhook create mydb --url https://ci.example.com/hooks/pscale --events branch.ready,deploy_request.opened

Test and manage webhooks

$ pscale webhook list mydb

List audit logs

$ pscale audit-log list --limit 50