CONCEPT Cited by 1 source

Unsharded-to-sharded migration¶

Definition¶

An unsharded-to-sharded migration is the specific variant of MoveTables that moves one or more tables from a single-instance (unsharded) keyspace to a multi-shard keyspace within the same Vitess cluster. Distinct from the broader migration cases the MoveTables primitive also supports:

Variant	Source	Target	Surface
External-source import	External MySQL	PlanetScale (unsharded or sharded)	PlanetScale Database Imports
Cross-cluster migration	Vitess cluster A	Vitess cluster B	`Migrate` workflow (planned)
Unsharded-to-sharded (this page)	Unsharded keyspace	Sharded keyspace, same cluster	PlanetScale Workflows
Table move within cluster	Keyspace A	Keyspace B, same cluster	`MoveTables` CLI

The unsharded-to-sharded variant is load-bearing because it is the mechanical step that solves the most common database-scaling regime shift: the point where a single primary can no longer handle the workload.

Why it is distinct from generic MoveTables¶

MoveTables can move tables between any two keyspaces, but the unsharded-to-sharded variant has distinguishing properties that the generic case does not:

Row-level routing changes. Every row on the source lives in a single keyspace. On the target, the row's shard is determined by its primary-vindex column — so the copy phase has to route each row to the correct target shard per the target keyspace's VSchema.
Sequence initialisation. The target sharded keyspace typically replaces auto-increment columns with Vitess Sequences (docs). SwitchTraffic initialises these sequences to avoid primary-key collisions post-cutover.
VSchema as first-class input. The customer has to have made the primary-vindex decision before the migration starts — which column to shard on, whether to use a lookup vindex for cross-shard uniqueness, how to handle ref tables. The quality of this decision determines the steady-state performance of the sharded system; no amount of migration-mechanism engineering compensates for a bad shard-key choice.
Cross-shard query implications. Any query that previously touched multiple rows on the unsharded source may now fan out to multiple shards on the target (scatter-gather) — which has performance, latency, and transactional implications the application must be engineered for.

Lifecycle¶

In the PlanetScale Workflows UI, the lifecycle is:

Build target topology in Cluster configuration — create the sharded target keyspace with VSchema, pick primary vindex, declare lookup vindexes if needed.
Create workflow — select source keyspace, target keyspace, tables to move. Runs validation pre-check.
Copying phase — per-target-shard VReplication streams row-copy from source ordered by primary key, each row filtered to its target shard by vindex. After copy, streams transition to continuous binlog replication tailing the source.
Verify data — run VDiff-equivalent pre-cutover consistency check.
Switch traffic — atomic routing-rule swap via SwitchTraffic; stops writes on source keyspace, buffers queries at proxy, initialises sequences on target, creates reverse VReplication workflow for rollback, flips routing rules to target, releases buffered queries. "Typically less than 1 second" (Source: sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale).
Optional: Switch back — reverse traffic via the reverse workflow created at step
Can be invoked arbitrarily many times.
Complete — tear down reverse workflow and migration-related routing-rule artefacts. Source keyspace can now be decommissioned.

Scaling-milestone framing¶

The unsharded-to-sharded migration is traditionally the single hardest operational milestone in a database's lifecycle. Doing it at all used to require:

Building or adopting a sharding substrate (often months of engineering).
Writing a custom data-motion pipeline (often double-write schemes + reconciliation).
Manually coordinating cutover (often downtime windows).
Hand-designing rollback procedures.

MoveTables + PlanetScale Workflows compress this to a configure-then-click operation by providing the sharding substrate (Vitess) + data-motion primitive (MoveTables) + cutover primitive (SwitchTraffic) + rollback primitive (reverse workflow). The quote that captures this verbatim: "Being able to easily and safely transition to a sharded environment shifts this phase of a company's existence from an extreme pain point to a smooth, well-tuned process." (Source: sources/2026-04-21-planetscale-introducing-sharding-on-planetscale-with-workflows.)

The claim is load-bearing for the data-motion mechanics but understates the upstream shard-key design work — see caveats on sources/2026-04-21-planetscale-introducing-sharding-on-planetscale-with-workflows.

Seen in¶

sources/2026-04-21-planetscale-introducing-sharding-on-planetscale-with-workflows — canonical wiki introduction. Ben Dicken's 2024-11-07 post introduces the unsharded-to-sharded variant of MoveTables as PlanetScale Workflows' first shipped workflow: "For this first release, we focused on supporting MoveTables, specifically when migrating a table from an unsharded keyspace to a sharded one. We believe that this is one of the most important workflows for our users, as it unlocks the ability to horizontally scale existing unsharded databases with minimal friction." Worked example: gymtracker unsharded + gymtracker- sharded target within the same PlanetScale database.