auto-migrate never adds new StrEnum members to an existing Postgres enum type — runtime 'invalid input value for enum' on evolved models

[0x054]

Summary

auto_migrate=True creates Postgres native enum types for StrEnum fields at table-creation time, but never evolves them: adding a member to the Python StrEnum after the type exists in the database is silently ignored by the migration planner. The first query or insert using the new member then fails at the database with invalid input value for enum <type>: "<value>" — an unhandled exception at runtime, invisible to any test that runs against a freshly-created schema (fresh schemas get the complete enum, so the gap is structurally untestable from the app side).

Repro

1. Model with class Provider(StrEnum): PLAID = "plaid" and a field provider: Provider; connect(..., auto_migrate=True) — table + provider enum type created with one label.
2. Add MX = "mx" to the StrEnum. Reconnect with auto_migrate=True against the same database — no DDL is planned.
3. Model.where(lambda m: m.provider == Provider.MX) → invalid input value for enum provider: "mx".

Real-world hit

pinch-backend M13 (syn54x/pinch-backend#93) added MX = "mx" to ConnectionProvider (created in M7 with only plaid). Every test was green — the suite's throwaway schemas always create the enum complete — and every existing database 500s on the first MX request. Found in a local smoke test; production would have hit it on deploy.

Suggested fix

The auto-migrate diff should compare the StrEnum's members against pg_enum for the existing type and emit ALTER TYPE <name> ADD VALUE IF NOT EXISTS '<value>' for each missing label (append-only; PG12+ allows it inside a transaction with the caveat that the new value is unusable until commit — emitting it outside the main migration transaction, or as its own autocommit statement, sidesteps the older-PG restriction entirely). Removed/renamed labels are a genuinely hard problem and can stay out of scope — additive evolution covers the overwhelmingly common case and is what silently breaks today.

Possibly related context: #199 touches enum ADD COLUMN planner divergence (native enum vs varchar resolution), but this issue is about evolving an existing enum type's value set, not column creation.

[0x054]

Confirmed and specced — the full spec is #329 (ready-for-agent), produced from a design session that also landed ADR-0011 and glossary terms (enum label, label addition) for this area.

The diagnosis here was verified exactly as written: the only enum DDL ferro emits is the idempotent CREATE TYPE guard (a no-op once the type exists), and the ALTER path explicitly never reconciles live native-enum columns. The suggested fix — append-only ALTER TYPE ... ADD VALUE IF NOT EXISTS, executed outside the migration transaction, removals out of scope — is what the spec adopts, computed from a single label diff in the Rust core and consumed by both auto-migrate and a new Alembic autogenerate comparator, so both migration doors see the same drift.

One decision reframes the repro as written: label addition is reconciliation-pass work, gated by migrate_updates=True — an existing enum type is an existing schema object, the same line ADR-0010 drew for indexes after #324. Step 2's reconnect with auto_migrate=True alone will therefore still plan no DDL by design (the create pass stays introspection-free and silent about drift of every kind); with migrate_updates=True the missing label is appended at boot and the new member round-trips. The extra-label direction (member removed from the model while rows still hold it) warns loudly and never acts.

For the pinch-backend case specifically: the fix requires migrate_updates=True on the deployments that should evolve, and the auto-migrate docs will carry the "fresh schemas can't test this" trap prominently for anyone running create-only.