CONCEPT Cited by 2 sources

Near-atomic schema deployment¶

Definition¶

Near-atomic schema deployment is the property that a set of schema changes grouped into one deployment unit (a PlanetScale deploy-request, a migration branch) cuts over together, a few seconds apart, rather than hours apart. It is not transactional atomicity in the database sense — the engine can only serialise DDL statements, so the cut-overs of N migrations are applied sequentially over a short window — but from the application's perspective there is one event rather than N, and the deployment is cancellable as a unit at any moment up to that event.

Canonical verbatim framing from the Shlomi Noach post:

"With MySQL, it is not possible to transactionally and atomically make changes to multiple table schema definitions. If you want to CREATE one table, ALTER another, and DROP a third, you must run these changes in some order. For this reason, we use the term 'near-atomically.'"

(Source: sources/2026-04-21-planetscale-deploying-multiple-schema-changes-at-once)

Why it matters¶

The traditional multi-ALTER failure mode is a rolling partially-deployed window — if three large-table changes each take 8 hours, running them sequentially leaves the schema in a semantically-inconsistent state for 24 hours straight. During that window:

The deployment is only partially reversible — the already- completed changes cannot be cancelled, only reverted via a new DDL.
The schema does not match what's in source control; any new deploy-request stacked on top has ambiguous base state.
Incident response is complicated — if an incident takes priority, pausing / cancelling the deployment leaves the schema in an intermediate state with no clear forward path.

Near-atomic deployment collapses this window from 24 hours to a few seconds. The 8-hour migrations still run for 8 hours, but they run in parallel in the staging phase and cut over together at the end. The partially- deployed window shrinks to the cut-over window (seconds).

Mechanism¶

Near-atomic deployment composes three primitives:

Shadow- table online schema change provides the copy-and-swap emulation of ALTER TABLE. Each long-running migration can independently reach a "ready to complete" state (staged-then- sealed) where it has fully copied the existing data and is tailing the binlog waiting for cut-over.
schemadiff equivalence- class analysis groups dependent diffs into connected components and computes a valid in-order execution permutation within each component. Cross-class ordering is arbitrary; within-class ordering respects dependencies. See concepts/schema-diff-equivalence-class.
Staged coordination — the deploy controller holds all long-running migrations in catch-up until each reports ready, then applies the cut-over to every migration in rapid sequence, followed by the immediate changes (CREATE TABLE, ALTER VIEW) that were deferred to the end.

Why "near-atomic" and not "atomic"¶

MySQL can only execute one DDL statement at a time — the engine has no multi-table schema transaction primitive analogous to BEGIN ... COMMIT over DML. Vitess cannot invent one either, because it sits on top of MySQL. The hard cut-overs happen sequentially — "a few seconds apart."

From the application's perspective, this is operationally equivalent to atomic:

The sum of cut-over times is small (seconds).
VTGate buffers queries during each cut-over, so clients observe latency, not errors.
The deployment is cancellable as a unit up to the first cut-over — partial-completion is not an observable state from outside the staging period.

But it is not atomic in the formal ACID sense — an incident during the cut-over window could leave some migrations completed and some not. The post acknowledges this as a structural limitation of building on MySQL.

Contrast with atomic transactions¶

Near-atomic schema deployment is orthogonal to atomic distributed transactions:

Dimension	Atomic distributed transaction	Near-atomic schema deployment
Scope	Multi-participant DML writes	Multi-table DDL
Guarantee	All-or-nothing commit	Stage-together + cut-over-in-seconds
Protocol	2PC / coordinator + participants	VReplication staging + schemadiff ordering
Primitive supported by MySQL?	Yes, via Vitess (experimental)	No (engine-level), emulated above
Rollback	Engine-level	Via reverse-order revert + inverse replication

Vitess ships both — the Vitess 21 release notes confirm atomic distributed transactions were reintroduced with "deeper integration with... Online DDL and VReplication." The two are complementary: DDL uses near-atomic because transactional DDL is not available; cross-shard DML uses atomic distributed transactions when strict atomicity is required.

Seen in¶

sources/2026-04-21-planetscale-gated-deployments-addressing-the-complexity-of-schema-deployments-at-scale — earliest wiki canonicalisation of "near-atomic" as PlanetScale's first-party framing. Shlomi Noach's 2022 Gated Deployments launch post: "While not strictly atomically, the deployment can be considered more atomic; up till the final stage, no change is reflected in production." The 2022 post also canonicalises the cross-shard dimension of near-atomicity — "the switch then takes place almost simultaneously (though not atomically) on all shards" — which the 2023 successor post inherits as background. See concepts/multi-shard-schema-sync for the cross- shard coordination mechanism.
sources/2026-04-21-planetscale-deploying-multiple-schema-changes-at-once — canonical wiki framing. Shlomi Noach: "PlanetScale deploys your entire set of changes near-atomically, which means the production database schema remains stable throughout the deployment process and changes almost all at once when all changes are ready." The 8-hour / 24-hour worked example; the cancel-before-sealed framing; the MySQL-engine-atomicity-limit reasoning; the "we also use this with PlanetScale's gated deployments" cross- reference to the gated deployment feature.