explain-differ

Overview ¶

Command explain-differ dumps the planned PHYSICAL plan shape of every query in the yamsql conformance corpus to a stable text baseline, and diffs two such baselines.

RFC-183 §6 deliverable: removing the nil-inner shell plans changes plan hashes and costs, which can silently flip which plan wins. A flipped-but- still-correct plan passes every row-level test, so the corpus-wide plan diff is the only check that can see it.

Typical use — before/after a planner change:

git stash                                              # or a worktree on master
go run ./cmd/explain-differ dump -out /tmp/before.txt
git stash pop
go run ./cmd/explain-differ dump -out /tmp/after.txt
go run ./cmd/explain-differ diff /tmp/before.txt /tmp/after.txt

`diff` exits 1 when the baselines differ, so it drops straight into CI or a pre-merge gate.