Skip to content

CONCEPT Cited by 2 sources

Cut-over freeze point

Definition

The cut-over freeze point is the single brief moment in an online schema change (or a data-motion migration) at which the source table is made write-locked on the server so the source and the shadow table can be declared equivalent at a specific GTID position and then atomically swapped. It is the only moment in the entire migration when the source-side engine blocks writes; every other step (backfill, change-log tracking, replication catch-up) is deliberately non-blocking.

The operator-facing promise in a zero-downtime system is that the freeze point is still not application-visible: a proxy layer (buffers queries) so clients see latency rather than errors. The freeze point is server-side; the query buffer is client-facing; these are two different layers of invisibility, both required to make the cut-over truly zero-downtime.

Why it's mandatory

Two tables that both take writes cannot be declared equivalent without some moment of synchronisation. The shadow has been catching up continuously, but "continuously" has a lag — bounded, small, measurable, but nonzero. To prove equivalence we need to:

  1. Stop new writes on the source.
  2. Drain any in-flight writes already in the binlog but not yet applied to the shadow.
  3. Read the source's current GTID and persist it as the equivalence marker.
  4. Apply the swap.

Everything in this sequence must happen atomically enough that no write lands in a window where "apply to source" is still valid but "apply to shadow" is no longer active. Hence the write lock: it is the primitive that forces the serialisation window.

The MySQL shape (from the post)

Cut-over for a VReplication- driven online DDL:

  1. Impose write lock on the source table — "the single step where a write lock is explicitly imposed on the table. Until the swap is complete, no writes can take place."
  2. Drain and apply any pending change-log events so the shadow is at exactly the source's current GTID.
  3. Mark the freeze-point GTID — "The Vitess migration flow marks the database position at that freeze point."
  4. Swap tables — "It then swaps the two tables: the shadow table replaces the original table, and the original table replaces the shadow table."
  5. Release the lock, resume normal serving. VTGate releases any queries it was holding.

Why the freeze-point GTID matters even after cut-over

In platforms like Vitess that run pre-staged inverse replication to support instant revert, the freeze-point GTID is the shared reference point that makes the inverse replication stream coherent:

  • Forward direction (cut-over onwards): the new table is primary; every write lands there.
  • Inverse direction (post-cut-over): every write on the new table is tailed from the binlog and applied to the now-former-primary. Both streams agree that the freeze- point GTID is "when the tables were equivalent" — without that shared marker, the inverse stream has no well-defined origin.

Shlomi Noach / Holly Guevara frame the freeze point as "the 'freeze point,' where both tables are in perfect sync" — the words matter: "perfect sync" is what is true at exactly the GTID marker, and what the inverse-replication stream re-establishes the invariant of for every subsequent write.

Seen in

  • sources/2026-04-21-planetscale-behind-the-scenes-how-schema-reverts-work — canonical wiki naming of the term "freeze point". Guevara + Noach: "The cut-over is the single step where a write lock is explicitly imposed on the table. Until the swap is complete, no writes can take place. It's the 'freeze point,' where both tables are in perfect sync. However, since downtime is unacceptable during this process, writes will still be allowed from the application's perspective. We'll hold all new writes that come in and apply them once the swap has taken place." The architectural point is doubly load-bearing: the freeze point both makes the forward swap correct and gives the inverse-replication stream its well-defined origin for the instant-revert feature.
  • sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale — the same primitive at the data-motion scale. MoveTables SwitchTraffic imposes source-keyspace write-stop, buffers queries at VTGate, waits for VReplication to fully drain, then flips routing rules. The freeze point at that level is keyspace-scoped, not table-scoped, but the shape is identical: a brief stop, a drain, a GTID mark, an atomic swap of routing rules. Documented as "less than 1 second" in wall-clock cost.
Last updated · 319 distilled / 1,201 read