Skip to content

SYSTEM Cited by 1 source

MoveTables

What it is

MoveTables (vitess.io docs) is Vitess's user-facing workflow wrapper for a common data-motion shape: copy tables from one place to another and keep them in sync until cutover. It composes VReplication for the data motion, VDiff for pre-cutover verification, and routing-rule updates for the cutover itself.

MoveTables is the primitive underlying PlanetScale's Database Imports feature — external-MySQL-to-PlanetScale migrations are MoveTables workflows. (Source: .)

Key operations

  • MoveTables Create — start the workflow. Provisions per-target-shard VReplication streams that enter the row-copy phase, then transition to continuous binlog replication once the copy is done.
  • MoveTables SwitchTraffic — perform the cutover. Pre-checks tablet health + replication lag + workflow state; locks source and target keyspaces in the topology server plus a named lock on the workflow; stops writes on source; buffers incoming queries (concepts/query-buffering-cutover); waits for replication to fully catch up; creates a reverse VReplication workflow (target → source) so rollback is possible (concepts/reverse-replication-workflow); initialises Vitess Sequences if tables are being sharded; allows writes on target; updates schema routing rules to send queries to target; starts reverse workflow; freezes original workflow; releases locks. "Typically take less than 1 second." See patterns/routing-rule-swap-cutover.
  • MoveTables ReverseTraffic — flip back to the source keyspace using the reverse workflow created at SwitchTraffic. Can be called as many times as needed until the customer is confident in the new system. See patterns/reverse-replication-for-rollback.
  • MoveTables Complete — finalise the migration after the customer is confident. Tears down the reverse workflow and migration-related routing-rule artefacts. Once this is called, the source system can be decommissioned.

Why it shows up on this wiki

MoveTables is the canonical wiki instance of a workflow primitive that composes data motion + verification + cutover + rollback into a single addressable unit. It is what turns VReplication (a low-level per-stream replication primitive) into a usable product surface. PlanetScale's Database Imports is literally a thin GUI over MoveTables + MoveTables SwitchTraffic + MoveTables Complete. At the mechanical level:

  • Migration = MoveTables Create
  • Long-running verification = repeated VDiff / resume
  • Test-your-app-against-the-new-system = application redirects to PlanetScale, traffic proxied back via routing rules until cutover
  • Cutover = MoveTables SwitchTraffic
  • Stay reverse-ready = keep the reverse workflow running
  • Rollback = MoveTables ReverseTraffic (as many times as needed)
  • Final commit = MoveTables Complete

The reverse workflow + routing-rule swap together are what make cutover reversible without data loss — a property critical when the new system differs from the old on axes (MySQL version, unsharded → sharded, charset / collation, query-optimiser behaviour) that only manifest under production traffic.

Seen in

  • sources/2026-04-21-planetscale-dealing-with-large-tables — Ben Dicken (PlanetScale, 2024-07-10) canonicalises MoveTables as the data-motion primitive for the vertical-sharding rung of the three-rung scaling ladder. The canonical worked example is splitting musclemaker into musclemaker_main (cold tables, downsized to 16 vCPU / 32 GB) and musclemaker_log (the hot table, 32 vCPU / 64 GB / 4 TB) via vtctldclient MoveTables --workflow musclemakerflow create --target-keyspace musclemaker_log --source-keyspace musclemaker --tables "exercise_log" → (hours pass) → ... switchtraffic. Canonical wiki disclosure that the copy phase and the cutover are independently scheduled primitives — production traffic routes to the source keyspace throughout the copy, then cutover is a near-instant routing-rule swap. Pedagogical altitude; no production numbers; the petabyte-scale altitude is on .

  • — canonical wiki disclosure of the unsharded-to- sharded table-migration variant of MoveTables as PlanetScale's first self-service sharding workflow (Ben Dicken, 2024-11-07). Exposes MoveTables as the Vitess primitive underneath the new PlanetScale Workflows dashboard UI with the verb mapping Create workflow → MoveTables Create, Verify data → VDiff, Switch traffic → MoveTables SwitchTraffic, Switch back → MoveTables ReverseTraffic. First canonical wiki enumeration of the full Vitess workflow family (MoveTables, Reshard, Materialize, LookupVindex, Migrate) directly from the post body. Canonicalises unsharded- to-sharded migration as a distinct MoveTables variant with its own lifecycle properties (primary- vindex row routing, Vitess Sequences initialisation at SwitchTraffic, cross-shard query implications). The 2021 Raju post documents external- source → PlanetScale imports; the 2026-02 Lord post documents the atomic-swap cutover design at petabyte scale; this 2024-11 post documents the unsharded→sharded variant within a single PlanetScale database as a self-service product.

  • — earliest canonical wiki disclosure that PlanetScale Database Imports is built on the MoveTables / VReplication stack (Phani Raju, 2021). Names Vitess unmanaged tablet as the composition primitive under the import workflow and canonicalises the database-as-data-router cutover variant — an earlier product-UX shape where the destination transparently proxies writes back to the source during a bidirectional validation phase, with cutover driven by an operator ("Enable primary mode" button) rather than SwitchTraffic. The 2026-02-16 Matt Lord post describes the atomic-swap design; this 2021 post documents the earlier direction-reversal design. Both share the same underlying mechanics (VReplication + routing rules + reverse replication + unmanaged tablet) and the same reversibility guarantee.

  • — canonical wiki description of MoveTables' SwitchTraffic sequence (pre-checks → keyspace locking → write stop + query buffer → replication catch-up → reverse workflow creation → sequence init → allow target writes → routing-rule swap → start reverse workflow → freeze original → release locks), and the ReverseTraffic + Complete lifecycle. Framed as the user-facing wrapper over VReplication + VDiff that PlanetScale's Database Imports feature is built on.

Last updated · 542 distilled / 1,571 read