Add V161: case-insensitive phoenix_kit_users.username via citext

[timujinne]

Why

Two accounts existed in production with the usernames Pavel and pavel. Nobody created a duplicate on purpose — the system allowed it end to end:

• phoenix_kit_users_username_uidx is a plain btree on a varchar column, so the two values are distinct keys.
• unsafe_validate_unique(:username, …) compares exactly.
• get_user_by_username/1 is Repo.get_by(User, username: …) — also exact.

The mechanism that actually produced the duplicate is worth spelling out, because it is systematic rather than a fluke: generate_username_from_email/1force-downcases, while ensure_unique_username/3 checks availability case-sensitively. A username set manually with a capital is therefore invisible to the generator — it proposes the lowercase form, finds it "free", and adds no suffix.

The consequence worse than the duplicate itself: signing in by username is case-sensitive too, so typing your own name with different capitalisation lands you in a different account. To the user that reads as "my permissions disappeared", with no error anywhere.

email is unaffected — it has been citext since V01 and is deliberately left alone.

What

V161 converts phoenix_kit_users.username to citext.

Postgres decides comparison semantics from the column type, so one ALTER fixes uniqueness and every lookup, including a bare Repo.get_by. A functional unique index on lower(username) would have fixed only the constraint and left every read exact-match — and nothing would stop the next lookup from forgetting about case again. This is also the pattern already used in this schema (email in V01, CRM columns in V151), not a new one.

• Pre-check before any DDL: GROUP BY lower(username) HAVING count(*) > 1, raising and naming the offending value (same shape as V106's). WHERE username IS NOT NULL matters — without it GROUP BY folds every NULL into one group and two username-less accounts abort the upgrade.
• Idempotent ALTER guarded on udt_name, prefix honored, @disable_ddl_transaction true.
• down/1 converts back to varchar(255).

Verification

Run against a real PostgreSQL 17.4, empty database, so the whole chain executed from V01 to V161:

• username → citext, email untouched, schema version comment 161
• phoenix_kit_users_username_uidx survived the ALTER with the same name and predicate
• inserting 'ALICE' against an existing 'alice' is rejected by the index
• WHERE username = 'BOB' finds the row stored as 'bob' — the exact SQL shape Repo.get_by emits
• varchar → citext confirmed binary-coercible against pg_cast (castmethod = 'b'), so no table rewrite; the index rebuild was confirmed on a scratch table (relfilenode changes), which is what makes the constraint start rejecting case variants

Full suite with a database: 3 failures, all in MaintenanceTest (scheduling windows on an unseeded database), which V161 does not touch. mix precommit green.

Also here

Verifying the above was harder than it should be, so two adjacent fixes ride along:

• config/test.exs hardcoded phoenix_kit_test, which forces a role with CREATEDB — precisely what a shared or managed instance withholds. PGDATABASE/PGPOOL now let you point the suite at a database you already have. Defaults unchanged.
• AGENTS.md described mix precommit as the local equivalent of CI "including tests with PostgreSQL". It never ran mix test, and CI is workflow_dispatch, so in practice nothing ran the Elixir suite. Adding mix test to precommit was tried and reverted — the suite is not green from a clean checkout (with no database ~5 "unit" tests fail because Settings reads hit the DB on a cache miss), and a permanently red gate teaches people to ignore the gate. The docs now say running the suite is manual, and warn that mix test with no database excludes every integration test and still reports success — the failure mode that matters most when the change is a migration.

Compatibility

An installation that already contains case-variant usernames stops at V160 with a raise naming the conflict, resolves it, and re-runs — the same operator experience V106 already establishes. Nothing is merged or renamed automatically. Installations without collisions are unaffected. citext has been a required extension since V01, so there is no new database prerequisite.

The behavioural change is the fix itself: username lookup and uniqueness become case-insensitive. registration_test.exs had a test pinning the old exact-match behaviour as intended; it is inverted here.

[timujinne]

Code review

Reviewed by an independent model (GLM-5.2, max effort) against the code, with every finding
re-verified by hand before being accepted — a review posted to a PR costs maintainer time when it
is wrong. Full write-up committed to
dev_docs/pull_requests/2026/681-case-insensitive-username/CLAUDE_REVIEW.md.

Verdict: APPROVE. Two findings, both now fixed in this branch.

IMPROVEMENT - MEDIUM — a set-but-empty env var aborted config loading

System.get_env/2 falls back to its default only when the variable is unset. A set-but-empty
PGPOOL= returns "", so String.to_integer("") raised an ArgumentError while config was
loading — before any test ran, with a message that never named PGPOOL. Reachable by
PGPOOL= mix test, or by PGPOOL: with no value in a YAML pipeline.

Fixed: PGDATABASE and PGPOOL now treat empty as absent and trim whitespace, and a non-numeric
PGPOOL raises a message naming the variable and the value. Checked across unset / set-empty /
valid / whitespace-padded.

NITPICK — internal chronology in upstream-facing docs

Comments read "tried on 2026-08-04 and reverted". A bare date without an actor reads as one team's
internal history in a public library. Dates dropped, reasoning kept.

Self-correction

This PR's own text claimed mix test with no database "silently" excludes integration tests. It is
not silent — test_helper.exs prints a warning banner. The point that matters survives: the run
still exits 0 and reports success, so a green summary proves nothing about a migration. Wording
corrected here and in AGENTS.md, since fixing inaccurate documentation with inaccurate
documentation would be a poor trade.

Checked and found correct

• Dispatch is Module.concat([__MODULE__, "V#{pad_idx}"]) by version number plus the
  @current_version bump — no registry to forget.
• The pre-check cannot false-positive: WHERE username IS NOT NULL is load-bearing, since
  GROUP BY otherwise folds every NULL into one group and two username-less accounts would abort
  the upgrade. Pinned by test.
• Re-running against an installation already at 161 is a no-op — coordinator skips, the DO block
  is guarded on udt_name, and the pre-check returns empty on a citext column.
• Prefix-safety: both existence checks anchor on table_schema, no ::regclass in an IMMEDIATE
  check, escaped_prefix escaped at the entry point. Same shape as V151.
• get_user_by_username/1, unsafe_validate_unique/3 and ensure_unique_username/3 all ride the
  column's semantics, so no call-site changes are needed.
• No internal infrastructure leaked into the diff.

On the evidence behind the migration

The claims in the description are from an actual run, not inference: PostgreSQL 17.4, empty
database, whole chain V01→V161. Column became citext, the unique index survived the ALTER with
the same name and predicate, 'ALICE' against an existing 'alice' was rejected, and
WHERE username = 'BOB' found 'bob' — the exact SQL shape Repo.get_by emits. Full suite on
that database: 3 failures, all in MaintenanceTest (scheduling windows on an unseeded database),
which V161 does not touch.