Resharding a Live Vitess Keyspace with MoveTables: What Actually Happens During Cutover

The problem: adding shards without stopping writes

Your keyspace has outgrown its shard count. In a plain MySQL setup, adding shards means downtime: stop the application, dump the data, reload it into the new topology, and repoint clients. Vitess MoveTables approaches this differently. It treats resharding as a controlled replication workflow. The original shards remain the system of record until the final moment, and traffic moves in stages. The practical consequence is that you can add capacity without a maintenance window, but you inherit a short write freeze at the end whose length depends on how well you prepared.

How the workflow moves rows

MoveTables is built on VReplication, Vitess's internal change-data-capture mechanism. When you start a resharding workflow, Vitess creates the target shards, copies a snapshot of the existing rows, and then streams binlog events from the source shards to keep the replicas current. The source shards stay authoritative. Writes continue to land on the old shards while the new ones catch up.

You can watch this through the workflow status commands. The exact subcommand names differ between vtctl and vtctldclient and across Vitess versions, so confirm the syntax for your deployment. In general, polling workflow status and VReplication lag tells you whether the target shards are ready for cutover.

Where rows land: vindexes decide the topology

Resharding is not just copying bytes. The destination of each row is determined by your keyspace VSchema—the metadata that defines how tables map to shards—and its vindexes. A vindex is a function that maps a column value to a shard. If you use a hash vindex on the sharding key, the same key always lands on the same target shard. That determinism is what makes the copy predictable.

Lookup vindexes are different. They use an indirection table to map a non-sharding-key column to the sharding key. That lookup table must be rebuilt and kept consistent during the copy, or queries that rely on it will fail after cutover. If your schema uses auto-increment primary keys, you also need a sequence table or explicit ID assignment before resharding. Without it, new shards can generate colliding IDs. Vitess does not enforce cross-shard foreign keys, so referential integrity remains an application concern regardless of how the rows are distributed.

The cutover: reads first, writes second, freeze last

Cutover is staged. Vitess switches reads to the target shards first, then writes. The write switch introduces a brief freeze while VReplication drains any remaining events. Enabling reverse replication before cutover makes rollback fast if the new layout misbehaves.

The workflow lifecycle has two endpoints that matter operationally. Cancelling the workflow drops it and leaves the source shards authoritative. Completing the workflow removes the source shards after traffic has fully moved. The distinction is critical: Cancel is safe before you are confident; Complete is destructive to the old topology.

Worked example: checking readiness before the write switch

Imagine you are resharding a keyspace named orders from two shards to four. The copy has been running for hours. Before you switch writes, you need to confirm the target shards are current. You run the status command from a host that can reach your vtctld service, using an account with workflow-read permissions:

vtctldclient --server=vtctld.example.com:15999 \
  workflow-status --keyspace=orders --workflow=reshard_2026

You are looking for two things: VReplication lag near zero, and no long-running transactions still open on the source shards. If lag is high or a transaction has been running for minutes, the write freeze will be prolonged. The right decision is to wait, investigate the lagging stream, and retry the check. Proceeding anyway turns a two-second freeze into a multi-second or multi-minute outage.

Trade-offs and limitations

The write freeze is the main operational risk. Long-running transactions and lagging replicas extend it, so you must size and monitor the window. Large tables and secondary indexes increase copy time and replication lag; a table with billions of rows and several secondary indexes can take far longer to copy than the raw row count suggests.

Sequence tables and lookup vindexes are common sources of post-reshard bugs when they are not created and backfilled before cutover. Resharding also changes the shard topology, so any code, dashboards, or connection strings that hardcode shard names or tablet aliases must be updated in step with the cutover.

What to do before you run this in production

• Rehearse in staging. Clone a production-scale dataset into a staging keyspace and run the full workflow. Record the observed write-freeze duration and VReplication lag.
• Inspect the VSchema. Use the schema-inspection commands to confirm vindex coverage and that no queries depend on cross-shard joins that will now fail.
• Verify after cutover. Compare row counts and checksums per shard between source snapshots and target shards to confirm completeness.
• Plan the rollback. Enable reverse replication before cutover so you can switch back quickly if the new layout misbehaves.

MoveTables removes the downtime from resharding, but it does not remove the preparation. The workflow is observable, reversible until you complete it, and deterministic if your vindexes are correct. Treat the write freeze as a budget you have to earn through rehearsal, not a guarantee you get for free.