Skip to content

CONCEPT Cited by 1 source

Diff-overlap auto-adaptation

Definition

Diff-overlap auto-adaptation is the schema three-way merge rule that treats identical sub-diffs shared between two concurrent branches as benign and auto-resolves them at merge time — rather than flagging them as conflicts under a naive commutativity check.

When two branches both apply the same ALTER TABLE … statement (e.g., both add the same name column with the same type and default), mechanical composition would fail on the second application. The auto-adaptation rule recognises the identical overlap, lets whichever branch merges first apply the shared change, and re-computes the second branch's remaining diff against the new baseline — dropping the already-applied change.

Canonical verbatim framing (Noach, 2023 PlanetScale):

*"Both branches create the same name column on customer, and then each branch proceeds to make other unrelated changes. Thanks to schemadiff, each of the changes (ALTER, CREATE, …) is fully formalized and we can analyze the changes one by one.

Is there a conflict with the new name column? Given that both branches completely agree on that particular change, PlanetScale's three-way merge considers this as an overlap and allows it. Should branch1 merge first, branch2's diff auto-adapts and is left to the creation of tbl2 only."* (Source: sources/2026-04-21-planetscale-database-branching-three-way-merge-for-schema-changes)

Mechanism

Given main, branch1, branch2 where both branches share an identical sub-diff:

  1. schemadiff decomposes each branch's diff into individual DDL statements.
  2. The system compares statements pairwise between diff1 and diff2. Identical matches are identified as overlaps.
  3. At merge time, the first branch to cut over applies its full diff (including the shared sub-diff).
  4. The second branch's diff is re-computed against the new post-merge main. Because the shared sub-diff is now part of main, it drops out of the second branch's remaining diff — leaving only the non-shared changes to apply.

The net effect: the shared change is applied once, correctly, rather than twice (which would fail) or flagged as a conflict (which would force manual intervention).

Worked example

Baseline main:

CREATE TABLE customer (id int, PRIMARY KEY (id));

Branch1: 

-- branch1 adds name column + creates tbl1
customer(id, name, PRIMARY KEY(id))
tbl1(id, PRIMARY KEY(id))

Branch2: 

-- branch2 adds name column + creates tbl2
customer(id, name, PRIMARY KEY(id))
tbl2(id, PRIMARY KEY(id))

Decomposed diffs:

  • diff1 = { ALTER TABLE customer ADD COLUMN name …, CREATE TABLE tbl1 … }
  • diff2 = { ALTER TABLE customer ADD COLUMN name …, CREATE TABLE tbl2 … }

Both contain the identical ALTER TABLE customer ADD COLUMN name …. Under a pure commutativity check:

  • diff1(diff2(main)) would fail — can't add name twice. Would flag conflict.
  • diff2(diff1(main)) would also fail. Would flag conflict.

With auto-adaptation:

  • branch1 merges → main becomes customer(id, name, …), tbl1(…).
  • branch2's diff re-computes → shared ALTER drops out; remaining diff is just CREATE TABLE tbl2 ….
  • branch2 merges cleanly.

No developer intervention required.

Why this exemption is principled

The purpose of the commutativity check is to detect cases where the developers disagree about the schema. When both branches propose the exact same change, the developers agree — the change is intended and consistent. A naive mathematical check would flag this false positive; the policy layer short-circuits it.

Contrast with column-order conflict: there, the branches disagree on column positioning, even though they agree the column should exist. That's a genuine conflict.

Dependency on DDL formalisation

Auto-adaptation requires that each diff statement be "fully formalized" by schemadiff — i.e., represented as a structured object (not a textual SQL string). Two ALTER TABLE customer ADD COLUMN name … statements must be recognisable as identical even if they differ in whitespace, backtick placement, or keyword case. schemadiff's AST-level representation makes this comparison reliable.

A textual diff tool would struggle: ALTER TABLE \customer` ADD COLUMN `name` varchar(255)andalter table customer add column name varchar(255)` are textually distinct but semantically identical. Only a parser-aware comparison can auto-adapt reliably.

Limitations

  • Exact-match only. Near-identical sub-diffs (e.g., both add name but with different default values) are not auto-adapted. They are genuine conflicts.
  • Order of merge matters for side effects. Auto- adaptation is deterministic only for the shared sub-diff. If the two branches' other changes create a column-order-sensitive asymmetry, the conflict may still appear in the non-shared portion.
  • No cross-branch identification of semantic equivalence. Two ADD COLUMN name varchar(255) and ADD COLUMN name varchar(255) DEFAULT '' are not treated as overlapping — even though they might be equivalent in intent. The check is syntactic on the parsed DDL object.

Seen in

Last updated · 550 distilled / 1,221 read