What are workflows?

Workflows are Vitess VReplication workflows. PlanetScale supports MoveTables and Materialize on Vitess branches. You create and drive workflows with pscale branch vtctl (or the matching APIs). The dashboard shows the live state of each workflow, read directly from Vitess.

​

Move tables between keyspaces

Move tables from one keyspace to another within your PlanetScale database:

• Unsharded to sharded: Move tables from an unsharded keyspace to a new sharded keyspace. This is the primary way to shard existing tables. See the Sharding quickstart.
• Sharded to sharded: Move tables between sharded keyspaces to change the number of shards. See Modifying the number of shards.
• Unsharded to unsharded: Move tables from one unsharded keyspace to another unsharded keyspace.

​

Import a database

To import an external internet-accessible MySQL database, you first connect it to your production branch as an external keyspace. Then you run a workflow with the external keyspace as the source and your PlanetScale keyspace as the target. The import copies your data, replicates new changes in real time, and switches traffic to PlanetScale with no downtime. For a full walkthrough, see the Database imports documentation.

​

MoveTables lifecycle

Every MoveTables workflow follows the same lifecycle:

1. Create: move-tables create copies the table schemas to the target keyspace and starts copying rows.
2. Copy: Vitess copies the existing rows from the source to the target. Streams are Copying.
3. Replicate: Once the copy finishes, Vitess keeps the target up to date with every new write on the source. Streams are Running.
4. Verify: Optionally compare the source and target with vdiff.
5. Switch traffic: move-tables switch-traffic moves replica traffic, then primary traffic, to the target keyspace. move-tables reverse-traffic moves it back.
6. Complete: move-tables complete stops replication. Its required flags decide whether the moved tables are dropped from the source keyspace and whether the routing rules are removed. You can also cancel a workflow at any point before it is complete.

Use move-tables status between steps. It shows each table’s copy progress, each stream’s state, and the traffic state. JSON output includes a next_steps field with the command to run next. See the move-tables reference for every command and flag.

​

Materialize

Materialize keeps target tables in sync in near-realtime. Targets can be copies, aggregations, or views defined by a SELECT against a single source table. Prefer MoveTables when you only need to move whole tables between keyspaces. Prefer Materialize when the target needs a different schema or a query that filters or aggregates rows.

1. Create with --table-settings JSON that names each target table and its source_expression.
2. Show until streams are replicating.
3. Read from the target tables once they are in sync.
4. Stop / start to pause and resume, or cancel to tear the workflow down.

See the materialize reference for flags and examples, and the Vitess Materialize docs for SELECT limitations.

​

View workflows in the dashboard

Select your database and click Workflows in the left nav. Pick a branch to see MoveTables and Materialize workflows on it, across all keyspaces or filtered to one keyspace. The list shows each workflow’s type. Open a MoveTables workflow to see:

• The source and target keyspaces, replication lag, and when the workflow last updated
• Which keyspace is serving reads and writes
• Each stream’s state, rows copied, and any error message
• Each table’s copy progress
• The results of the latest VDiff

Open a Materialize workflow to see stream states, replication lag, and each target table with the query that feeds it. The Workflows page is read-only. To create, switch, complete, or cancel a workflow, use pscale branch vtctl move-tables or pscale branch vtctl materialize.

​

Earlier workflows

Workflows created with pscale workflow create, the earlier dashboard workflow pages, or the /workflows API endpoints are managed separately from MoveTables and Materialize workflows. pscale workflow and the /workflows API endpoints are deprecated. Use pscale branch vtctl move-tables, pscale branch vtctl materialize, and the matching APIs for new work.

​

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.