Add V163: repair uuid columns that are not primary keys

[mdon]

Fixes a reported production defect: phoenix_kit_email_events with uuid as character varying(255), nullable, no default, and no primary key, on a database upgraded through the whole chain since V01. 149 other tables were correct, so this was one table falling out of the conversion rather than a broken upgrade.

Why the chain missed it — three times

The reporter identified V40's guard. There is a second cause they could not see from outside the repo, and it is the one that explains why they are still broken at V162.

1. V40's guard tests EXISTENCE, not TYPE. An older release created the column as Ecto :string, so unless column_exists?(table, :uuid, …) was already true and V40 skipped the table wholesale — not just the ADD COLUMN, but the backfill, the SET NOT NULL and the unique index with it. The table is in V40's @tables_to_migrate; being listed did not help.

2. V56's type conversion shipped 17 days after V56 did.ensure_all_uuid_columns_native_type/2 converts exactly this varchar column — and it was added to V56 on 2026-03-02, while V56 itself shipped 2026-02-13. A recorded version never re-runs, so every host that crossed V56 in that window kept the broken column permanently. V56's NOT NULL and index repairs also run off hardcoded table lists that phoenix_kit_email_events appears in none of.

3. V74 did not verify its own post-condition. It dropped the legacy bigint id but could not promote uuid to primary key — wrong type, nullable — and its moduledoc's claim ("after V74, every PhoenixKit table has uuid as its PK") silently became false.

What this adds

V163 — catalog-driven repair. Every previous attempt enumerated tables by hand and this table was absent from every list, including the list in the migration written to repair its class of problem. V163 asks the catalog which tables are actually wrong, so a table nobody remembered to list is repaired anyway.

PhoenixKit.Migrations.UUIDIntegrity — the detection and SQL, shared by the migration and the task so they cannot drift. Drift in a primary-key repair is how a table ends up half-fixed.

mix phoenix_kit.repair_uuid — the operator path for tables too large to rewrite during a deploy. Supports --dry-run, --prefix, and specific table names, and builds the unique index CONCURRENTLY because it runs outside a transaction.

Doctor — a new primary-key check, plus a correction to the existing one.

Deliberate decisions

Large tables are deferred, not silently rewritten.ALTER COLUMN TYPE rewrites under ACCESS EXCLUSIVE and ADD PRIMARY KEY builds an index under the same lock — both O(rows). On a big events table behind PgBouncer (which the reporter runs) that is pool exhaustion during mix ecto.migrate, not a pause. Above two million rows the repair is skipped and logged with the exact command; the doctor keeps reporting it until it is done.

Nothing raises on the happy path. The reporter suggested V74 verify and fail. Raising on an already-shipped chain would strand every affected host mid-deploy, and a library does not own its hosts' deploy runbooks. Turning "one audit table lacks a PK, on a version where no schema maps to it" into a fleet-wide failed deploy is the worse outcome. The doctor is the loud channel.

The version marker is written even when a table is skipped. An unwritten marker is how this codebase has previously had migrations skipped permanently. A skipped table stays visible; a stale marker does not.

The doctor's remedy was incomplete and is corrected. It suggested ALTER TABLE <t> ALTER COLUMN uuid TYPE uuid USING uuid::uuid, which restores the type but not the NOT NULL, the UUIDv7 default, or the primary key — anyone following it literally was left in a state that still fails the check. It now points at the task. The "will crash Ecto on load" wording is also softened: on 1.7.235 no schema maps to this table, so it overstated the impact, exactly as the reporter noted.

Review found two defects in this change

Both were caught by an adversarial pass over the diff and are fixed here:

• The per-table isolation could never have fired.Ecto.Migration.execute/1queues a command, so the statements were flushed after up/1 returned — outside the rescue. A locked table would still have aborted every later repair and skipped the marker. flush/0 now runs them in scope. This compiled and read correctly while doing nothing, which is the kind of defect a diff hides.
• Identifiers were interpolated unquoted. A legal-but-unusual table name produced a syntax error that aborted the run. quote_ident/1 now quotes both prefix and table; there is a test with a space in the name.

Verification

• 2881 tests, 0 failures; mix precommit exit 0
• 16 new integration tests, all against a synthesized broken database — no fresh install produces this state, so the damage has to be manufactured to prove the repair. Covers detection, type conversion, backfill, NOT NULL, PK, value preservation, de-duplication, idempotency, the non-castable abort, statement ordering, and identifier quoting.
• Applied end-to-end on a real 164-table dev database: correctly found nothing to repair, wrote the marker, V162 → V163, doctor's new check PASS.
• Prefix-safe: no ::regclass anywhere (it raises when the relation is absent and aborts the transaction), every existence check anchored on table_schema/nspname, Helpers.uuid_v7_call/1 for the generator.

No version bump or CHANGELOG entry — left at the current version deliberately.

One thing I could not attribute: an intermittent single failure in test/integration/phoenix_kit_web/live/users/media_test.exs ("orphan filter false omits orphaned param"). It passes in isolation on both a clean tree and this branch, appears seed-dependent, and is unrelated to migrations — but it did not appear on the one clean-tree full run I did, so I am flagging it rather than asserting it is pre-existing.