CONCEPT Cited by 1 source

Pre-staged inverse replication¶

Definition¶

Pre-staged inverse replication is the architectural property that, after an online schema change (or data- motion cut-over) completes, the migration's shadow table and its VReplication stream are not torn down. Instead they are kept alive, and a second replication stream is immediately created in the opposite direction (new table → old table) so the old table stays current with every post-cut-over write. The resulting state:

The new table serves live production traffic.
The old table, which still has the old schema, is now the inverse shadow — a pre-populated, live-updated mirror of what production would look like under the old schema.
A VReplication stream runs continuously, projecting every commit on the new table back through the DDL's inverse column-mapping onto the old table.

The consequence: a schema revert is not a data copy. It is a second atomic cut-over swap of two tables that are already in sync, run in a click.

Contrast with post-hoc reverse replication¶

The generalisation of this idea — creating a reverse replication stream at cut-over so rollback is possible without data loss — is documented separately on the wiki as patterns/reverse-replication-for-rollback (applied to data-motion migrations: MoveTables SwitchTraffic primes a reverse VReplication workflow so ReverseTraffic can swap back). The schema-revert application of the same idea is narrower:

	patterns/reverse-replication-for-rollback	Pre-staged inverse replication
Scope	Data-motion migration (imports, reshards, table moves)	Online DDL (one table, schema change)
What's reversed	Which keyspace/shard is authoritative	Which schema is authoritative
Cost	Reverse workflow = linear in write rate × retention horizon	Inverse replication + retained shadow table = same shape
Unique to this post	—	"Unlike any other schema change solution, Vitess does not terminate upon migration completion"

The post frames this as a general design principle that Vitess instantiates, not a one-off feature: the data-motion and schema-change flavours both rest on keeping the VReplication stream alive past cut-over so the inverse direction can be served without a fresh data copy.

Why other online-DDL tools can't do this¶

pt-online-schema-change and gh-ost both build shadow tables for their migrations, but both tear them down at cut-over:

The shadow is dropped (or marked for cleanup) — there's no table to invert into.
The change-log stream is terminated — the tool exits as soon as the swap completes.
The forward-projection code (DDL semantics, column-mapping) is in-process — it's gone the moment the migration binary exits.

To retrofit instant revert onto those tools you'd need a long-lived out-of-band agent to keep the shadow populated. VReplication already is that long-lived out-of-band agent — it's a sidecar-state-persisting pipeline running on the VTTablet, not a standalone migration binary — so keeping it alive past cut-over is free (software-wise; the replication-stream CPU + retained-shadow-storage cost is non-trivial).

Column projection on revert¶

The DDL being reverted is generally not bijective on the data shape. The post's walked example — ALTER TABLE users DROP COLUMN title — shows the asymmetry: forward direction drops the column; reverse direction has to reintroduce it; rows added after cut-over have no value for it. The canonical shape of the asymmetry:

DROP COLUMN c — on revert, rows added post-cut-over get c = NULL (or the column's default). Post: "Savannah doesn't have a title. This is because that entry was added after the tables were swapped, so the title column didn't exist in production. This is expected and something you can clean up after the revert, if necessary."
ADD COLUMN c (reverting the add) — on revert, rows written to the new schema lose their c values. Data in that column is discarded.
MODIFY COLUMN c TYPE1 → TYPE2 — on revert, values may need a reverse cast; not every TYPE2 → TYPE1 cast is total (truncation, loss of precision, charset narrowing).
CREATE TABLE / DROP TABLE — explicitly called out in the post as "more nuances" requiring a future post. The clean table-inversion trick doesn't compose (forward: "no table" → "table"; inverse shadow for the "no table" side has no origin).

The load-bearing property is that the revert retains the rows written post-cut-over; information that was only representable in the new schema is inherently lost when projecting back.

Seen in¶

sources/2026-04-21-planetscale-behind-the-scenes-how-schema-reverts-work — canonical wiki instance. Holly Guevara and Shlomi Noach name the distinguishing architectural property directly: "Unlike any other schema change solution, Vitess does not terminate upon migration completion. This point is important when it comes to reverting schema changes." And the mechanism itself: "Shortly after migration completion, PlanetScale prepares an open-ended revert. The revert process tracks ongoing changes to the table and applies them to a shadow table. That should sound familiar. Indeed, we already have a shadow table in place. It is already populated with data, and we know that it was in full sync with what we now call the new table at cut-over time." The claim about being "unlike any other schema change solution" is not validated by this wiki page against the current pt-online-schema-change / gh-ost implementations — it is the post's own framing and an accurate characterisation as of the post's content.