sqlb-survey: the whole-database adoption report (#112)

[jryannel]

An adoption currently discovers what the DSL cannot express one table at a time, because the only way to ask is to write a throwaway program (#112). This is that program, kept.

Why three phases

The flat skip list is not the question an adopter has.

• Phase A introspects the whole schema — what a drift gate over the whole database would see.
• Phase B introspects every table alone. This is what makes the result triageable: introspect reports per construct, but the gate is per registry, so one unmodelable table takes its whole module out (A composite PRIMARY KEY has no declaration, so every natural-key table pays for a surrogate it does not need #109). Per-table isolation names the blocked tables instead of leaving them mixed into a list of skips.
• Phase C renders the modelled registry into a scratch database and re-introspects, separating a construct that survives import but not the round trip from one that never imported.

Result on a 68-table production schema

clean — imports with nothing dropped	57
partial — imports, constructs dropped	11
refused	0
skipped constructs / distinct reasons	15 / 6
DDL statements to rebuild	329
apply failures	0
residual after round trip	8

The 8 residuals are 4 CHECK constraints dropped and re-added. Every one is on a varchar(n) column; the three text columns carrying the same kind of IN list round-trip clean. Postgres normalises the list two different ways depending on the column type:

-- varchar column, as stored
CHECK (status::text = ANY ((ARRAY['backlog'::varchar, …])::text[]))
-- what the re-emitted DDL normalises to
CHECK (status::text = ANY (ARRAY[('backlog'::varchar)::text, …]))

Semantically identical, textually different. Worth knowing whether that belongs here or in the adopter's schema — for the subject above it was cheaper to move the columns to text, which ADR-0017 wanted anyway.

One finding that is the tool's own setup

Diff renders no CREATE EXTENSION, so bootstrapping into a bare database fails once per table with function uuid_generate_v4() does not exist rather than once with the missing extension named. With uuid-ossp and vector pre-created, the same 329 statements applied cleanly. That is recorded in the command's doc comment; whether Diff should emit extensions is a separate question and not decided here.

Notes

• Imports pgx and sqlb only — the dependency gate is unaffected.
• go build and go vet clean.
• Not wired into cmd/sqlb as a subcommand. If No 'sqlb introspect' subcommand: the first step of every adoption is the only one with no shell, and diagnosing a refusal means writing a throwaway program #112 lands as sqlb introspect, this is the behaviour to fold in; keeping it separate first means the report shape can change without touching the released CLI surface.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Scg4WyZ3hV6ZqLjQPL2ckK

---

Generated by Claude Code