PlanetScale pscale CLI: Every Command Explained (2026)

The pscale CLI is your primary interface for managing PlanetScale databases, but its true power lies in how it abstracts away complex database operations into simple, intuitive commands.

Let’s see it in action. Imagine you need to create a new database and a new branch for development.

# Create a new PlanetScale database
pscale database create my-awesome-app-db --region us-east-1

# Create a new branch from the main branch
pscale branch create my-awesome-app-db main --name feature/new-login

These two commands, seemingly simple, initiate a cascade of operations within PlanetScale. The create database command provisions a new database instance, allocating resources and setting it up in the specified region. The create branch command, on the other hand, doesn’t just copy data; it creates a lightweight, isolated schema with its own set of credentials and a unique connection string, all while referencing the same underlying data as the parent branch. This allows for safe, independent development and testing without impacting production.

The pscale CLI is structured around core entities: database, branch, schema, deploy, log, and token.

pscale database: This group handles the lifecycle of your databases. You can list them (pscale database list), create new ones (pscale database create), show details of a specific database (pscale database show <database-name>), and delete them (pscale database delete <database-name>). When you create a database, you’re not just spinning up a MySQL instance; you’re provisioning a fully managed, scalable, and highly available database service with features like automatic backups and read replicas.
pscale branch: Branches are fundamental to PlanetScale’s workflow. They allow you to isolate changes, develop features, and test them before merging them into your production schema. Commands include list (pscale branch list <database-name>), create (pscale branch create <database-name> <source-branch> --name <new-branch-name>), show (pscale branch show <database-name> <branch-name>), deploy (covered next), revert (pscale branch revert <database-name> <branch-name>), and delete (pscale branch delete <database-name> <branch-name>). Creating a branch is an instantaneous operation because it’s a schema-level change, not a data copy.
pscale schema: While branches represent isolated development environments, the schema is the actual structure of your database (tables, columns, indexes, etc.). The schema commands allow you to inspect and manage this. Key commands are show (pscale schema show <database-name> <branch-name>) which displays the SQL definition of your schema, and diff (pscale schema diff <database-name> <branch-name-a> <branch-name-b>) which highlights the differences between two branches’ schemas. This diff command is crucial for understanding what changes a deployment will introduce.
pscale deploy: This is where the magic of PlanetScale’s branching truly shines. A deploy represents the act of merging changes from one branch into another, typically from a feature branch into main. The command pscale deploy create <database-name> <source-branch> <target-branch> initiates a deployment. PlanetScale then performs a schema diff. If there are no conflicts, it applies the changes to the target branch. If there are conflicts (e.g., a column dropped in target-branch that was modified in source-branch), it will prompt you to resolve them. This process is designed to be non-disruptive, allowing schema changes to be applied with zero downtime.
pscale log: For auditing and debugging, the log commands provide visibility into database activity. pscale log list <database-name> <branch-name> shows recent query logs, while pscale log slow <database-name> <branch-name> can help identify performance bottlenecks by showing slow queries. This gives you direct insight into what your application is actually doing with the database.
pscale token: Authentication to PlanetScale is managed via API tokens. pscale token list shows your active tokens, pscale token create generates a new one (you’ll need to specify scopes like read, write, admin), and pscale token delete revokes them. These tokens are used by the pscale CLI itself and any other tools that need to interact with the PlanetScale API programmatically.

The most surprising thing about PlanetScale’s branching is that creating and switching between branches doesn’t involve copying data. When you create a branch, PlanetScale creates a new, independent schema history that points to the same underlying data storage. Changes made in a branch are applied to this new schema history, and only when you deploy are those schema changes merged into the target branch’s history. This makes branching and merging incredibly fast and efficient.

Once you’re comfortable with managing your databases and branches, the next logical step is to explore how to integrate PlanetScale with your CI/CD pipeline using the pscale CLI.