> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale CLI commands: keyspace

## Getting started

Make sure to first [set up your PlanetScale developer environment](https://planetscale.com/docs/cli/planetscale-environment-setup.md). Once you've installed the `pscale` CLI, you can interact with PlanetScale and manage your databases straight from the command line.

## The `keyspace` command

This command allows you to view your keyspaces, create internal or [external keyspaces](#create-an-external-keyspace), resize them, [configure disk scaling](#configure-disk-scaling), and view or update your Vitess VSchemas. This command is not available for Postgres databases.

**Usage:**

```bash theme={null}
pscale keyspace <SUB-COMMAND> <FLAG>
```

### Available sub-commands

| **Sub-command** | **Sub-command flags** | **Product** | **Description** |
| :- | :- | :- | :- |
| `create <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--cluster-size <SIZE>`, `--additional-replicas <NUMBER>`, `--shards <NUMBER>` | Vitess | Create a new keyspace within a database branch. |
| `create-external <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--host <HOST>`\*, `--source-database <NAME>`\*, `--username <USER>`\*, `--password <PASSWORD>`\*, `--ssl-mode <MODE>`\*, `--port <PORT>`, `--cluster-size <SIZE>`, `--ssl-certificate-authority <CA>`, `--ssl-client-certificate <CERT>`, `--ssl-client-key <KEY>`, `--ssl-server-name <NAME>`, `--min-tls-version <VERSION>`, `--tablet-cell <CELL>`, `--skip-lint-errors`, `--dry-run`, `--wait` | Vitess | Create an external keyspace by connecting a production branch to an existing MySQL database. |
| `delete <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--force` | Vitess | Delete a keyspace from a database branch. |
| `list <DATABASE_NAME> <BRANCH_NAME>` | | Vitess | List all keyspaces within a database branch. |
| `parameters list <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--namespace <NAMESPACE>` | Vitess | List a keyspace's VTTablet and MySQL [parameters](https://planetscale.com/docs/vitess/cluster-configuration/parameters.md) with their current and default values. |
| `parameters set <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--parameters <NAMESPACE.NAME=VALUE>`, `--reset <NAMESPACE.NAME>` | Vitess | Change VTTablet and MySQL parameters on a keyspace, or set them back to their defaults. |
| `parameters changes list <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--page <NUMBER>`, `--per-page <NUMBER>` | Vitess | List parameter changes to a keyspace and their state. |
| `parameters changes show <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> <CHANGE_ID>` | | Vitess | Show a parameter change. |
| `parameters changes cancel <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> <CHANGE_ID>` | | Vitess | Cancel a parameter change that hasn't started applying. |
| `show <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Show a specific keyspace within a database branch. |
| `read-only-regions <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | List [read-only regions](https://planetscale.com/docs/vitess/scaling/read-only-regions.md) for a keyspace. |
| `resize <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--cluster-size <SIZE>`, `--additional-replicas <NUMBER>` | Vitess | Resize a keyspace, including external keyspaces. |
| `resize cancel <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Cancel an ongoing keyspace resize. |
| `resize status <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Show the status of the keyspace's last resize. |
| `settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Show the settings for a keyspace. |
| `update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `-i`, `--interactive`, `--disk-scaling-strategy <STRATEGY>`, `--max-rollout <NUMBER>`, `--max-storage <SIZE>`, `--replication-durability-constraints-strategy <STRATEGY>`, `--storage <SIZE>`, `--throttler-enabled`, `--throttler-threshold <SECONDS>`, `--vreplication-batch-replication-events`, `--vreplication-enable-noblob-binlog-mode`, `--vreplication-optimize-inserts` | Vitess | Update the settings for a keyspace. |
| `vschema show <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Show the VSchema for a sharded keyspace. Empty on non-sharded keyspaces. |
| `vschema update <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | `--vschema <FILE>`\* | Vitess | Update a VSchema of a keyspace. |
| `rollout-status <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>` | | Vitess | Check the status of a keyspace resize request. |

> \* *Flag is required*

#### Sub-command flag descriptions

| **Sub-command flag** | **Description** | **Applicable sub-commands** |
| :- | :- | :- |
| `--additional-replicas <NUMBER>` | `<NUMBER>` is the number of replicas to add to the keyspace. By default, production branches include 2 replicas. Do not use this flag for external keyspaces. | `create`, `resize` |
| `--cluster-size <SIZE>` | `<SIZE>` is the size of the database cluster. Optional for `create-external`; when omitted, PlanetScale chooses a size from the source storage. For `resize`, pass a size from `pscale size cluster list --external`. | `create`, `create-external`, `resize` |
| `--dry-run` | Check connectivity and schema compatibility without creating the keyspace. | `create-external` |
| `--host <HOST>` | Hostname of the external MySQL server. | `create-external` |
| `--min-tls-version <VERSION>` | Minimum TLS version for the external connection. | `create-external` |
| `--password <PASSWORD>` | Password for the external MySQL user. | `create-external` |
| `--port <PORT>` | Port of the external MySQL server. Default is `3306`. | `create-external` |
| `--skip-lint-errors` | Create even if datasource lint reports errors, when the organization allows it. | `create-external` |
| `--source-database <NAME>` | Name of the database on the external MySQL server, not the PlanetScale database. | `create-external` |
| `--ssl-certificate-authority <CA>` | CA certificate chain, or a path to a PEM file. | `create-external` |
| `--ssl-client-certificate <CERT>` | Client certificate, or a path to a PEM file. | `create-external` |
| `--ssl-client-key <KEY>` | Client private key, or a path to a PEM file. | `create-external` |
| `--ssl-mode <MODE>` | SSL verification mode: `disabled`, `preferred`, `required`, `verify_ca`, or `verify_identity`. | `create-external` |
| `--ssl-server-name <NAME>` | SSL server name override. | `create-external` |
| `--tablet-cell <CELL>` | Cell where the external tablet runs. | `create-external` |
| `--username <USER>` | Username to connect to the external MySQL server. | `create-external` |
| `--wait` | Wait until the keyspace is ready. | `create-external` |
| `--force` | Delete the keyspace without a confirmation prompt. Required in non-interactive or non-`human` output modes. | `delete` |
| `--disk-scaling-strategy <STRATEGY>` | How disk size is managed: `grow` automatically increases disk size as needed, up to `--max-storage`. `disable` turns off automatic disk growth. `shrink` resizes disks to `--storage` and then turns off automatic disk growth. | `update-settings` |
| `-i, --interactive` | Run the command in interactive mode. | `update-settings` |
| `--namespace <NAMESPACE>` | Only show parameters in this namespace: `vttablet` or `mysqld`. | `parameters list` |
| `--parameters <NAMESPACE.NAME=VALUE>` | Set a parameter, where `<NAMESPACE>` is `vttablet` or `mysqld`, for example `vttablet.vreplication-parallel-insert-workers=4`. Repeatable. | `parameters set` |
| `--reset <NAMESPACE.NAME>` | Set a parameter back to its default, for example `vttablet.vreplication-parallel-insert-workers`. Repeatable. | `parameters set` |
| `--page <NUMBER>`, `--per-page <NUMBER>` | Page through parameter changes. `--per-page` defaults to 25. | `parameters changes list` |
| `--max-rollout <NUMBER>` | Maximum number of shards to update concurrently during a keyspace rollout. Accepts values from 1 to 32. | `update-settings` |
| `--max-storage <SIZE>` | Maximum size disks can automatically grow to, in bytes or with a unit such as `200GiB` or `1TiB`. Must be at least the size of the largest current disk and no more than the organization's storage limit (4 TB by default). | `update-settings` |
| `--replication-durability-constraints-strategy <STRATEGY>` | Replication strategy to use. Options: maximum, dynamic, minimum (default "maximum"). | `update-settings` |
| `--throttler-enabled` | Pause schema migrations and VReplication workflows when replication lag is above the threshold. Pass `--throttler-enabled=false` to turn the throttler off. | `update-settings` |
| `--throttler-threshold <SECONDS>` | Replication lag in seconds above which migrations and workflows are paused. Default is 5. | `update-settings` |
| `--storage <SIZE>` | Disk size to shrink to, in bytes or with a unit such as `200GiB`. Must be a multiple of 1 GiB and no more than the organization's storage limit. Only accepted when the disk scaling strategy is `shrink`, either passed with `--disk-scaling-strategy` or already set on the keyspace. Rejected if any disk is using more than 80% of the requested size. | `update-settings` |
| `--shards <NUMBER>` | Number of shards in the keyspace (default 1). | `create` |
| `--vreplication-batch-replication-events` | When enabled, sends fewer queries to MySQL to improve performance. | `update-settings` |
| `--vreplication-enable-noblob-binlog-mode` | When enabled, omits changed BLOB and TEXT columns from replication events, which reduces binlog sizes. (default true) | `update-settings` |
| `--vreplication-optimize-inserts` | When enabled, skips sending INSERT events for rows that have yet to be replicated. (default true) | `update-settings` |
| `--vschema <FILE>` | `<FILE>` is the path to the updated VSchema file. | `vschema update` |

### Available flags

| **Flag** | **Description** |
| :- | :- |
| `-h`, `--help` | View help for auth command |
| `--org <ORGANIZATION_NAME>` | The organization for the current user |

### Global flags

| **Command** | **Description** |
| :- | :- |
| `--api-token <TOKEN>` | The API token to use for authenticating against the PlanetScale API. |
| `--api-url <URL>` | The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`. |
| `--config <CONFIG_FILE>` | Config file. Default is `$HOME/.config/planetscale/pscale.yml`. |
| `--debug` | Enable debug mode. |
| `-f`, `--format <FORMAT>` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. |
| `--no-color` | Disable color output. |
| `--service-token <TOKEN>` | The service token for authenticating. |
| `--service-token-id <TOKEN_ID>` | The service token ID for authenticating. |

## Examples

### Create an external keyspace

Attach an existing MySQL database as an external keyspace on a **production** branch. To [import its data into PlanetScale](https://planetscale.com/docs/vitess/imports/database-imports.md), create a [MoveTables workflow](https://planetscale.com/docs/cli/move-tables.md#import-from-an-external-keyspace) with the external keyspace as the source.

`--source-database` is the remote MySQL database name. The `--username` user must have the [import user permissions](https://planetscale.com/docs/vitess/imports/import-tool-user-requirements.md), and your database must allow connections from [PlanetScale's IP addresses](https://planetscale.com/docs/vitess/imports/import-tool-migration-addresses.md).

```bash theme={null}
pscale keyspace create-external <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --host db.example.com \
  --source-database commerce \
  --username import \
  --password secret \
  --ssl-mode required \
  --wait
```

Check compatibility without creating the keyspace:

```bash theme={null}
pscale keyspace create-external <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --host db.example.com \
  --source-database commerce \
  --username import \
  --password secret \
  --ssl-mode required \
  --dry-run
```

`--dry-run` reports connection failures, server setting and user grant errors, and schema lint errors. Connection, server setting, and grant errors stop the keyspace from being created. Table-level schema errors don't: fix those tables or leave them out of the import with `--exclude-tables`.

### Resize an external keyspace

Use the same `resize` command as an internal keyspace. Do not pass `--additional-replicas`.

```bash theme={null}
pscale keyspace resize <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --cluster-size <SIZE>
pscale keyspace resize status <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
```

You can also create and resize external keyspaces from the [Clusters](https://planetscale.com/docs/vitess/cluster-configuration.md) page in the dashboard.

### Delete an external keyspace

Deleting an external keyspace disconnects PlanetScale from your external database and removes its stored credentials. If you imported from it, complete the MoveTables workflow first.

```bash theme={null}
pscale keyspace delete <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
```

### Update tablet throttler settings

```bash theme={null}
pscale keyspace settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --throttler-enabled=false
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --throttler-threshold=10
```

### Update shard rollout concurrency

Set the maximum number of shards updated concurrently during keyspace configuration rollouts:

```bash theme={null}
pscale keyspace settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --max-rollout=4
```

`--max-rollout` accepts values from 1 to 32. If the API value is not set, `pscale keyspace settings` displays `not set`, and PlanetScale uses the default of 1.

### Configure disk scaling

Show the keyspace's current disk scaling strategy and storage sizes:

```bash theme={null}
pscale keyspace settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
```

Let disks grow automatically, up to a limit:

```bash theme={null}
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --disk-scaling-strategy grow \
  --max-storage 1TiB
```

Turn off automatic disk growth:

```bash theme={null}
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --disk-scaling-strategy disable
```

Shrink disks to a smaller size. Automatic disk growth is turned off afterwards:

```bash theme={null}
pscale keyspace update-settings <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --disk-scaling-strategy shrink \
  --storage 200GiB
```

The shrink is rejected if any disk is using more than 80% of the requested size. Settings you don't pass keep their current values. See [Disk autoscaling](https://planetscale.com/docs/vitess/cluster-configuration/disk-autoscaling.md) for how each option works.

### Change keyspace parameters

List a keyspace's VTTablet and MySQL [parameters](https://planetscale.com/docs/vitess/cluster-configuration/parameters.md), then change them. Changes for both namespaces are submitted together and roll out to the keyspace:

```bash theme={null}
pscale keyspace parameters list <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> --namespace vttablet
pscale keyspace parameters set <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --parameters vttablet.vreplication-parallel-insert-workers=4 \
  --parameters mysqld.wait_timeout=600
pscale keyspace parameters changes list <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
```

A change is `applying` while it rolls out and `completed` once every shard has it. A keyspace can have one unfinished change per namespace at a time. To set parameters back to their defaults, pass `--reset`:

```bash theme={null}
pscale keyspace parameters set <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME> \
  --reset vttablet.vreplication-parallel-insert-workers \
  --reset mysqld.wait_timeout
```

### List read-only regions for a keyspace

```bash theme={null}
pscale keyspace read-only-regions <DATABASE_NAME> <BRANCH_NAME> <KEYSPACE_NAME>
```

Output includes each region's slug, cluster size, and replica count. Use a region slug with `pscale password create ... --read-only-region` or `pscale database dump ... --read-only-region`.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.