> ## 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: move-tables export const PlatformAvailability = ({current, vitess, postgres, neki}) => { const docsHref = path => { if (!path) return path; const normalized = path.startsWith('/') ? path : `/${path}`; return normalized; }; const labels = { vitess: 'Vitess', postgres: 'Postgres', neki: 'Neki' }; const combinedLabels = { both: 'Vitess and Postgres', all: 'Vitess, Neki, and Postgres', 'postgres-neki': 'Postgres and Neki' }; if (combinedLabels[current]) { return
{combinedLabels[current]}
; } const hasVitess = current === 'vitess' || Boolean(vitess); const hasPostgres = current === 'postgres' || Boolean(postgres); const hasNeki = current === 'neki' || Boolean(neki); const only = [hasVitess, hasPostgres, hasNeki].filter(Boolean).length === 1; const engines = []; if (current === 'vitess' || current === 'postgres' || current === 'neki') engines.push(current); if (hasVitess && current !== 'vitess') engines.push('vitess'); if (hasNeki && current !== 'neki') engines.push('neki'); if (hasPostgres && current !== 'postgres') engines.push('postgres'); return
{engines.map(engine => { const isCurrent = current === engine; const href = docsHref(engine === 'vitess' ? vitess : engine === 'postgres' ? postgres : neki); const label = only ? `${labels[engine]} only` : labels[engine]; const state = isCurrent || !href ? 'current' : 'link'; if (isCurrent || !href) { return {label} ; } return {label} ; })}
; }; ## 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 `move-tables` command Run [Vitess MoveTables](https://vitess.io/docs/user-guides/migration/move-tables/) workflows on a Vitess database branch: copy tables from one keyspace to another, check copy and traffic state, switch reads then writes, and complete or cancel the workflow. JSON output includes a `next_steps` field with a suggested next command. Use it to see what to run after `list` or `status`. **Usage:** ```bash theme={null} pscale branch vtctld move-tables ``` ### Available sub-commands | **Sub-command** | **Sub-command flags** | **Description** | | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ | | `list ` | `--target-keyspace ` | List MoveTables workflows on the branch | | `create ` | `--workflow `\*, `--source-keyspace `\*, `--target-keyspace `\*, `--tables `, `--all-tables`, `--exclude-tables `, `--auto-start`, `--stop-after-copy`, `--defer-secondary-keys`, `--on-ddl `, `--sharded-auto-increment-handling `, `--global-keyspace `, `--source-time-zone `, `--tenant-id `, `--cells `, `--tablet-types `, `--atomic-copy` | Create a MoveTables workflow | | `show ` | `--workflow `\*, `--target-keyspace `\* | Show a workflow | | `status ` | `--workflow `\*, `--target-keyspace `\* | Show copy progress and traffic state | | `switch-traffic ` | `--workflow `\*, `--target-keyspace `\*, `--tablet-types `\*, `--dry-run`, `--initialize-target-sequences`, `--max-replication-lag-allowed ` | Switch traffic to the target keyspace | | `reverse-traffic ` | `--workflow `\*, `--target-keyspace `\*, `--tablet-types `, `--dry-run`, `--max-replication-lag-allowed ` | Switch traffic back to the source keyspace | | `complete ` | `--workflow `\*, `--target-keyspace `\*, `--keep-data`\*, `--keep-routing-rules`\*, `--rename-tables`, `--dry-run` | Finish the workflow and clean up | | `cancel ` | `--workflow `\*, `--target-keyspace `\*, `--keep-data`\*, `--keep-routing-rules`\* | Cancel a workflow that is still in progress | > \* *Flag is required* `list` also accepts the alias `ls`. Omit `--target-keyspace` on `list` to use the branch's default keyspace. #### Sub-command flag descriptions | **Sub-command flag** | **Description** | **Applicable sub-commands** | | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | | `--workflow ` | Workflow name | `create`, `show`, `status`, `switch-traffic`, `reverse-traffic`, `complete`, `cancel` | | `--source-keyspace ` | Keyspace to copy tables from | `create` | | `--target-keyspace ` | Keyspace to copy tables to. On `list`, defaults to the branch's default keyspace | `list`, `create`, `show`, `status`, `switch-traffic`, `reverse-traffic`, `complete`, `cancel` | | `--tables ` | Tables to move (comma-separated). Mutually exclusive with `--all-tables` and `--exclude-tables` | `create` | | `--all-tables` | Move all tables from the source keyspace | `create` | | `--exclude-tables ` | Tables to skip when moving (comma-separated) | `create` | | `--auto-start` | Start the workflow after creation (default `true`) | `create` | | `--stop-after-copy` | Stop the workflow after the copy phase | `create` | | `--defer-secondary-keys` | Defer secondary indexes until copy finishes (default `true`) | `create` | | `--on-ddl ` | DDL handling: `IGNORE`, `STOP`, `EXEC`, `EXEC_IGNORE` | `create` | | `--sharded-auto-increment-handling ` | `AUTO_INCREMENT` handling for sharded targets: `LEAVE`, `REMOVE`, `REPLACE` | `create` | | `--global-keyspace ` | Unsharded keyspace for sequence tables when `--sharded-auto-increment-handling` is `REPLACE` | `create` | | `--source-time-zone ` | Convert `DATETIME` values from this timezone to UTC | `create` | | `--tenant-id ` | Tenant ID for multi-tenant MoveTables | `create` | | `--cells ` | Cells to restrict the workflow to (comma-separated) | `create` | | `--tablet-types ` | Tablet types for the workflow or traffic switch (comma-separated). Use `REPLICA,RDONLY` for reads and `PRIMARY` for writes | `create`, `switch-traffic`, `reverse-traffic` | | `--atomic-copy` | Use atomic copy | `create` | | `--dry-run` | Show what would happen without applying it | `switch-traffic`, `reverse-traffic`, `complete` | | `--initialize-target-sequences` | Initialize target sequences when switching traffic | `switch-traffic` | | `--max-replication-lag-allowed ` | Maximum replication lag allowed before switching | `switch-traffic`, `reverse-traffic` | | `--keep-data` | Keep copied data in the target (`true`) or remove it (`false`) | `complete`, `cancel` | | `--keep-routing-rules` | Keep routing rules (`true`) or remove them (`false`) | `complete`, `cancel` | | `--rename-tables` | Rename source tables instead of dropping them | `complete` | ### Available flags | **Flag** | **Description** | | :-------------------------- | :------------------------------------ | | `-h`, `--help` | View help for `move-tables` | | `--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. | ## Lifecycle A typical MoveTables run looks like this: 1. **Create** the workflow and wait until copy finishes and streams are `Running`. 2. **Verify** with `pscale branch vtctld vdiff create`, then `vdiff show` until it completes with no mismatches. You can skip VDiff and switch replica traffic directly. 3. **Switch replica traffic** with `--tablet-types REPLICA,RDONLY`. 4. **Switch primary traffic** with `--tablet-types PRIMARY`. 5. **Preview cleanup** with `complete --dry-run`, then complete after you review the result. Use `status` between steps. `traffic_state` values are: * `Reads Not Switched. Writes Not Switched` * `All Reads Switched. Writes Not Switched` * `Reads Not Switched. Writes Switched` * `All Reads Switched. Writes Switched` ## Examples List MoveTables workflows and get the next command to run: ```bash theme={null} pscale branch vtctld move-tables list mydb main --org acme --format json ``` Create a workflow: ```bash theme={null} pscale branch vtctld move-tables create mydb main \ --org acme \ --workflow commerce2customer \ --source-keyspace commerce \ --target-keyspace customer \ --tables customers,orders \ --format json ``` Check copy and traffic state: ```bash theme={null} pscale branch vtctld move-tables status mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --format json ``` Example `status` JSON after replica traffic has switched: ```json theme={null} { "traffic_state": "All Reads Switched. Writes Not Switched", "next_steps": [ { "command": "pscale branch vtctld move-tables switch-traffic mydb main --org acme --workflow commerce2customer --target-keyspace customer --tablet-types PRIMARY --format json", "reason": "Switch primary traffic after validating replica traffic" } ] } ``` Switch replica traffic, then primary traffic: ```bash theme={null} pscale branch vtctld move-tables switch-traffic mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --tablet-types REPLICA,RDONLY \ --format json pscale branch vtctld move-tables switch-traffic mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --tablet-types PRIMARY \ --format json ``` Verify with VDiff before switching traffic: ```bash theme={null} pscale branch vtctld vdiff create mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --format json pscale branch vtctld vdiff show mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --uuid \ --format json ``` Preview cleanup, then complete: ```bash theme={null} pscale branch vtctld move-tables complete mydb main \ --org acme \ --workflow commerce2customer \ --target-keyspace customer \ --keep-data=false \ --keep-routing-rules=false \ --dry-run \ --format json ``` ## 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.