;
};
## Getting Started
Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup). Once you've installed the `pscale` CLI, you can interact with PlanetScale and manage your databases straight from the command line.
## The `branch` command
This command allows you to create, delete, diff, and manage [branches](/docs/vitess/schema-changes/branching).
**Usage:**
```bash theme={null}
pscale branch
```
### Available sub-commands
| **Sub-command** | **Sub-command flags** | **Description** | **Product** |
| :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------- |
| `connections ` | `show`, `top`, `kill`, `kill-transaction` | Inspect and act on live branch connections. See the [`connections` reference](/docs/cli/connections). | Postgres, Vitess |
| `create ` | `--from `, `--region `, `--restore `, `--restore-point `, `--seed-data`, `--wait` | Create a new branch on the specified database | Postgres, Vitess |
| `delete ` | `--force`, `--delete-descendants` | Delete the specified branch from a database | Postgres, Vitess |
| `demote ` | | Demote a production branch to development | Vitess |
| `diff ` | `--web` | Show the diff of the specified branch against the parent branch. | Vitess |
| `extensions list ` | | List the extensions available on a Postgres branch's cluster image | Postgres |
| `lint ` | | Lint the schema of a branch | Vitess |
| `list ` | `--web` | List all branches of a database | Postgres, Vitess |
| `parameters list ` | `--namespace `, `--extension`, `--internal` | List the configuration parameters of a Postgres branch | Postgres |
| `promote ` | | Promote a database branch to production | Vitess |
| `query-patterns list ` | `--limit `, `--starting-after ` | List query pattern reports for a branch. See the [`query-patterns` reference](/docs/cli/query-patterns). | Postgres, Vitess |
| `query-patterns show ` | | Show a query pattern report. See the [`query-patterns` reference](/docs/cli/query-patterns). | Postgres, Vitess |
| `query-patterns delete ` | `--force` | Delete a query pattern report. See the [`query-patterns` reference](/docs/cli/query-patterns). | Postgres, Vitess |
| `query-patterns download ` | `--output ` | Generate and download a CSV report of branch query patterns. See the [`query-patterns` reference](/docs/cli/query-patterns). | Postgres, Vitess |
| `refresh-schema ` | | Refresh the schema for a database branch | Vitess |
| `resize ` | `--cluster-size `, `--replicas `, `--parameters `, `--wait`, `--wait-timeout ` | Change a Postgres branch's cluster size, replica count, or configuration parameters | Postgres |
| `resize status ` | | Show the latest change request for a Postgres branch | Postgres |
| `resize cancel ` | | Cancel the queued change request for a Postgres branch | Postgres |
| `routing-rules get ` | | Show the keyspace routing rules of a branch | Vitess |
| `routing-rules update ` | `--routing-rules `\* | Replace the keyspace routing rules of a branch | Vitess |
| `safe-migrations enable ` | | Enables safe migrations for a database branch | Vitess |
| `safe-migrations disable ` | | Disables safe migrations for a database branch | Vitess |
| `schema ` | `--web` | Show the schema of a branch | Vitess |
| `show ` | `--web` | Show a specific backup of a branch | Postgres, Vitess |
| `switch --database ` | `--database `\*, `--create`, `parent-branch ` | Switch to the specified branch | Postgres, Vitess |
| `switchover ` | `--candidate ` | Move the primary of a Postgres branch to a replica. See [Switchovers](/docs/postgres/troubleshooting/switchovers). | Postgres |
| `switchover list ` | `--page `, `--per-page ` | List switchovers for a Postgres branch | Postgres |
| `switchover show ` | | Show a Postgres switchover | Postgres |
| `update ` | `--new-name `, `--deletion-protected` | Rename a branch or change its deletion protection | Postgres, Vitess |
| `vtgate show ` | | Show the current VTGate configuration for a Vitess branch | Vitess |
| `vtgate resize ` | `--vtgate-size `, `--vtgate-count `, `--vtgate-max-count `, `--vtgate-autoscaling`, `--vtgate-target-cpu-utilization ` | Resize VTGates for a Vitess production branch | Vitess |
| `vtgate resize status ` | | Show the latest VTGate resize request for a Vitess branch | Vitess |
| `vtgate resize cancel ` | | Cancel a queued VTGate resize for a Vitess branch | Vitess |
### Service token automation: `branch`
Legend: โ supported ยท ๐ซ unavailable ยท ๐ค interactive login only. All sub-commands require `--org` or `PLANETSCALE_ORG`.
| Sub-command | Env-var auth | `--service-token` flag | Requires `--org` | Postgres / Vitess | `--format json` | API equivalent |
| :--------------------------- | :----------: | :--------------------: | :--------------: | :---------------- | :-------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list ` | โ | โ | โ | Both | โ | `pscale api organizations//databases//branches --format json` |
| `show ` | โ | โ | โ | Both | โ | `pscale api organizations//databases//branches/ --format json` |
| `create` / `delete` | โ | โ | โ | Both | โ | `POST pscale api organizations//databases//branches --format json` ยท `DELETE pscale api organizations//databases//branches/ --format json` |
| `schema ` | โ | โ | โ | Both | โ | `pscale api organizations//databases//branches//schema --format json` |
| `diff` / `promote` | โ | โ | โ | Vitess | โ | `pscale api organizations//databases//branches//schema/lint --format json` ยท `POST pscale api organizations//databases//branches//promote --format json` |
| `connections` | โ | โ | โ | Both | โ | `pscale branch connections top --org --format json` |
```bash theme={null}
export PLANETSCALE_ORG=""
pscale branch list --format json
pscale branch show --format json
```
Setup and commands to avoid: [CLI overview](/docs/cli) ยท [Service tokens](/docs/api/service-tokens#service-token-automation)
> \* *Flag is required*
#### Sub-command flag descriptions
Some of the sub-commands have additional flags unique to the sub-command. This section covers what each of those does. See the above table for which context.
| **Sub-command flag** | **Description** | **Applicable sub-commands** |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------- |
| `--from ` | Parent branch that you want to create a new branch off of | `create` |
| `--region ` | Region where database should be created | `create` |
| `--restore ` | Create a new branch from a specified backup | `create` |
| `--restore-point ` | For PostgreSQL, restore to a point-in-time recovery timestamp (for example `2023-01-01T00:00:00Z`). Requires `--restore` or `--from`. Cannot be used with `--seed-data`. | `create` |
| `--seed-data` | Create a new branch and seed data using the [Data Branchingยฎ feature](/docs/vitess/schema-changes/data-branching) | `create` |
| `--web` | Perform the action in your web browser | `create`, `diff`, `list`, `schema`, `show` |
| `--wait` | Wait until the branch is ready (`create`) or the change request completes (`resize`) | `create`, `resize` |
| `--major-version` | The major version of the branch (Postgres only). Currently supports `17` or `18`. | `create` |
| `--database ` | Specify the database name | `switch` |
| `--create` | Create a new branch if it does not exist | `switch` |
| `--parent-branch ` | If a new branch is being created, use this to specify a parent branch. Default is `main`. | `switch` |
| `--delete-descendants` | Recursively delete all descendant branches when deleting a branch | `delete` |
| `--limit ` | Number of query pattern reports to return, up to 100. | `query-patterns list` |
| `--starting-after ` | Fetch the next page of query pattern reports after a report ID. | `query-patterns list` |
| `--output ` | Write the query patterns CSV report to a specific file path. | `query-patterns download` |
| `--candidate ` | The replica to promote during a switchover, as returned by `pscale branch infra`. Omit to select automatically. | `switchover` |
| `--page ` | Page of results to fetch. | `switchover list` |
| `--per-page ` | Number of results per page. Default is `100`. | `switchover list` |
| `--new-name ` | New name for the branch | `update` |
| `--deletion-protected` | Protect the branch from deletion (`--deletion-protected=false` to disable) | `update` |
| `--routing-rules ` | JSON file with the routing rules to set on the branch | `routing-rules update` |
| `--cluster-size ` | New cluster size for the branch, as a fully-qualified SKU name (e.g. `PS_10_GCP_X86`). Use `pscale size cluster list --engine postgresql` to see the valid sizes. | `resize` |
| `--replicas ` | Desired number of replicas for the branch | `resize` |
| `--parameters ` | Set a configuration parameter (e.g. `pgconf.max_connections=200`). Repeat the flag to set multiple parameters. Use `pscale branch parameters list` to see available parameters. | `resize` |
| `--wait-timeout ` | Maximum time to wait for the change request to complete with `--wait`. Default is `10m`. | `resize` |
| `--namespace ` | Only show parameters in this namespace (e.g. `pgconf`, `pgbouncer`, `patroni`) | `parameters list` |
| `--extension` | Only show parameters that configure an extension (`--extension=false` hides them) | `parameters list` |
| `--internal` | Only show internal (immutable) parameters (`--internal=false` hides them) | `parameters list` |
| `--vtgate-size ` | VTGate size SKU (e.g. `VTG_320`, `VTG_1280`). Hyphens are accepted and converted to underscores. | `vtgate resize` |
| `--vtgate-count ` | Number of VTGates per availability zone (minimum when autoscaling is enabled) | `vtgate resize` |
| `--vtgate-max-count ` | Maximum VTGates per availability zone when autoscaling is enabled | `vtgate resize` |
| `--vtgate-autoscaling` | Enable or disable VTGate autoscaling (`--vtgate-autoscaling=false` to disable) | `vtgate resize` |
| `--vtgate-target-cpu-utilization ` | Target CPU utilization percent when autoscaling is enabled | `vtgate resize` |
The `--region` flag can not be used with `--restore` when creating a branch. Branch backups will be restored to their original region. `--restore-point` is PostgreSQL only. When you pass `--restore-point` without `--restore`, `--from` is required so the CLI can look up a backup that covers that timestamp.
### Available flags
| **Flag** | **Description** |
| :-------------------------- | :------------------------------------ |
| `-h`, `--help` | View help for auth command |
| `--org ` | The organization for the current user |
### Global flags
| **Command** | **Description** |
| :------------------------------ | :----------------------------------------------------------------------------------- |
| `--api-token ` | The API token to use for authenticating against the PlanetScale API. |
| `--api-url ` | The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`. |
| `--config ` | Config file. Default is `$HOME/.config/planetscale/pscale.yml`. |
| `--debug` | Enable debug mode. |
| `-f`, `--format ` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. |
| `--no-color` | Disable color output. |
| `--service-token ` | The service token for authenticating. |
| `--service-token-id ` | The service token ID for authenticating. |
## Examples
### The `connections` sub-command
**Command:**
```bash theme={null}
pscale branch connections top
```
Opens a live view of the branch's connection activity. It works for Postgres and Vitess branches; for
Vitess, pass `--keyspace` and `--shard` to target a tablet, or run interactively to select them. See
the [`connections` reference](/docs/cli/connections), [Inspect live Postgres connections](/docs/postgres/monitoring/connections),
and [Inspect live Vitess connections](/docs/vitess/monitoring/connections) for the full workflow.
### The `query-patterns` sub-command
**Command:**
```bash theme={null}
pscale branch query-patterns list --org
pscale branch query-patterns show --org
pscale branch query-patterns delete --org
pscale branch query-patterns download --org
```
List, inspect, and delete existing Query Insights reports for a branch. The `download` command creates
a new report, waits for it to finish generating, and downloads the CSV file. See the
[`query-patterns` reference](/docs/cli/query-patterns) for the full workflow.
### The `update` sub-command
**Command:**
```bash theme={null}
pscale branch update --new-name
pscale branch update --deletion-protected
pscale branch update --deletion-protected=false
```
Renames a branch or changes its deletion protection. Only the flags you pass are sent, and at least one
is required.
### The `extensions` sub-command
**Command:**
```bash theme={null}
pscale branch extensions list
```
Lists the extensions available on a Postgres branch's cluster image. This is the catalog the image can
load, not the result of `CREATE EXTENSION`. Preload libraries are configured with
`pscale branch resize --parameters`. See [Postgres extensions](/docs/postgres/extensions).
### The `switchover` sub-command
**Command:**
```bash theme={null}
pscale branch switchover --candidate
```
Moves the primary of a Postgres branch to a replica. With `--candidate`, the named replica is promoted; without it, an eligible replica is selected automatically. On a branch without replicas, the single instance is restarted in place instead. See [Switchovers](/docs/postgres/troubleshooting/switchovers) for the full workflow.
List past switchovers or show one by id. `switchover list` supports `--page` and `--per-page`.
```bash theme={null}
pscale branch switchover list
pscale branch switchover show
```
### The `list` sub-command with `--web` flag
**Command:**
```bash theme={null}
pscale branch list --web
```
**Output:**
Opens the Branches page, ``, in browser.
### The `parameters` sub-command
**Command:**
```bash theme={null}
pscale branch parameters list --namespace pgconf
```
Lists the configuration parameters of a Postgres branch, including their current values, defaults,
allowed ranges, and whether changing them requires a restart. Use `--namespace` to limit the output
to a single namespace such as `pgconf`, `pgbouncer`, or `patroni`.
### The `resize` sub-command
**Command:**
```bash theme={null}
pscale branch resize --parameters pgconf.max_connections=200 --parameters pgconf.work_mem=8MB --wait
```
Creates a change request for a Postgres branch. A single change request can update the cluster size
(`--cluster-size`), the number of replicas (`--replicas`), and configuration parameters
(`--parameters`, repeatable) together. With `--wait`, the command polls until the change request
completes; without it, the command returns immediately and you can follow up with `resize status`.
Some parameters require a database restart to take effect; the command tells you which ones before
the change is applied.
**Command:**
```bash theme={null}
pscale branch resize status
```
Shows the latest change request for the branch, including its state (`queued`, `pending`,
`resizing`, `completed`, or `canceled`) and what it changes.
**Command:**
```bash theme={null}
pscale branch resize cancel
```
Cancels the queued change request for the branch. Only change requests that have not started being
applied can be canceled.
### The `vtgate` sub-command
**Command:**
```bash theme={null}
pscale branch vtgate show
```
Shows the current VTGate size, count, and autoscaling settings for a Vitess branch.
**Command:**
```bash theme={null}
pscale branch vtgate resize \
--vtgate-size VTG_320 \
--vtgate-autoscaling \
--vtgate-count 2 \
--vtgate-max-count 8 \
--vtgate-target-cpu-utilization 50
```
Queues a VTGate resize for a Vitess production branch. Pass at least one of `--vtgate-size`,
`--vtgate-count`, `--vtgate-max-count`, `--vtgate-autoscaling`, or
`--vtgate-target-cpu-utilization`. Development branches cannot be resized. See the
[VTGate documentation](/docs/vitess/scaling/vtgates) for size defaults, autoscaling limits, and pricing.
**Command:**
```bash theme={null}
pscale branch vtgate resize status
```
Shows the latest VTGate resize request for the branch.
**Command:**
```bash theme={null}
pscale branch vtgate resize cancel
```
Cancels a queued VTGate resize. Only resize requests that have not started being applied can be
canceled.
### The `diff` sub-command
**Command:**
```bash theme={null}
pscale branch diff
```
**Output:**
```sql theme={null}
-- users --
+CREATE TABLE `users` (
+ `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+ `name` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL,
+ PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
This will return the diff against the parent branch.
## Need help?
Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join ourย [Discord community](https://pscale.link/community) to see how others are using PlanetScale.