Skip to content

CONCEPT Cited by 1 source

Pre-flight schema-conflict check

Definition

A pre-flight schema-conflict check is a conflict- detection pipeline that runs before a deploy request reaches cutover, rejecting the request if it would collide with any other concurrent schema change. It is the schema-layer analog of a Git merge-conflict check performed ahead of time — and distinct from, and strictly earlier than, the deploy queue's one-at-a-time serial execution guarantee. The goal is to fail fast: catch conflicts at request creation / queue admission rather than after waiting hours for a migration to reach cutover and then discover it can't proceed.

Canonical verbatim definition (Burns, 2021 PlanetScale):

*"To avoid migrating a schema change that will conflict with the production schema, PlanetScale analyzes the schema changes in advance of deployment.

When a user creates a deploy request, PlanetScale automatically checks for conflicts, analyzing the schema on the branch against the main branch schema at the time of the branching. PlanetScale also analyzes the schema changes against current schema on main, which may have changed in the time since the branch was created, ensuring that no conflicts exist."*

(Source: sources/2026-04-21-planetscale-non-blocking-schema-changes.)

The three checks

The 2021 PlanetScale post canonicalises a three-check pipeline:

Check 1 — branch-HEAD vs. main-HEAD-at-fork

Has the branch itself introduced any contradictions or invalid DDL since fork? This is the straightforward "what does this deploy request contain?" check — compares the branch's current schema to the schema that was forked from main when the branch was created.

Check 2 — branch-HEAD vs. main-HEAD-now

Has main drifted since the branch was forked? If main has since gained, dropped, or altered the same table / column the branch is touching, the branch's change set may no longer compose cleanly. Verbatim:

"PlanetScale also analyzes the schema changes against current schema on main, which may have changed in the time since the branch was created, ensuring that no conflicts exist."

Check 3 — branch-HEAD vs. queue-ahead deploy requests

The third check is queue-scoped: does this deploy request conflict with any other deploy request already queued ahead of it? Verbatim:

"when a user adds a deploy request to the deploy queue, PlanetScale checks the schema changes in the deploy requests ahead of that user's deploy request for any potential conflicts. If a conflict exists, the deploy request is rejected from the queue, and the user is notified of the conflict."

This is the critical scaling difference vs. a naive "wait-and-see" approach: without pre-flight queue conflict-checking, a team might queue five deploy requests behind a long-running migration and discover two of them are mutually incompatible only at cutover time, hours or days later.

Why it matters — days-of-savings disclosure

Verbatim from Burns:

"This prevents users from having to wait until it is their turn to deploy, only to discover unanticipated conflicts with their schema changes, and with longer running migrations, this can mean a time savings of up to a few days."

The savings come from moving the detection point earlier: without pre-flight, a conflict surfaces when the migration tries to cut over; with pre-flight, it surfaces at deploy-request creation / queue admission. The difference is the migration's backfill time — potentially hours to days on a petabyte-scale table.

Relationship to neighboring concepts

  • concepts/schema-diff-equivalence-class — the primitive for representing a schema change. The pre-flight conflict check composes multiple diffs and asks whether they all apply together.
  • Schema-change queue — the serialisation primitive that runs accepted deploy requests one at a time. The pre-flight check is the admission control in front of the queue; rejection means the request never enters the queue.
  • Deploy request — the primitive whose creation triggers checks 1 and 2; whose queue-add triggers check 3.
  • Database branching — provides the fork-point baseline that checks 1 and 2 diff against.
  • Vitess schemadiff — the later Vitess-era implementation of schema-diff computation that underlies these checks in a Vitess-based platform; PlanetScale's 2021 post predates the schemadiff name but describes the same capability.

Failure mode it prevents — avoidable cutover

failure

Without pre-flight conflict detection, the canonical failure mode is:

  1. Engineer A opens a deploy request renaming column x to y.
  2. Engineer B opens a deploy request renaming column x to z.
  3. Both pass lint individually.
  4. A's migration runs (hours).
  5. B's migration reaches cutover, discovers x doesn't exist any more, fails.

With the three-check pipeline, B's deploy request is rejected at queue admission because check 3 sees A's queued change to column x.

Seen in

Last updated · 378 distilled / 1,213 read