V188 unique indexes, a shared test-helper DB preflight, and a docs cleanup

[mdon]

Three changes on main. The V188 migration is the substantial one; the other
two are follow-ups from the same pass.

---

1. V188 — unique indexes for user connections, follows and blocks

The defect

The three phoenix_kit_user_connections schemas each declare a unique_constraint/3 naming an index:

• phoenix_kit_user_follows_unique_idx
• phoenix_kit_user_blocks_unique_idx
• phoenix_kit_user_connections_requester_recipient_uidx

None of the three has ever existed.unique_constraint/3 only translates a database violation into a changeset error, so with no index there is no violation — the constraints were inert, and the module's read-then-write pre-check was the only guard. Two concurrent follows, blocks or requests both pass that check and both insert.

Directed vs undirected — the part worth reviewing

Follows and blocks are directed: "A follows B" and "B follows A" are two different relationships, so those index the ordered pair.

Connections are undirected — one row is one relationship, stored in whichever direction it was asked — so that index is an expression index on (LEAST(requester_uuid, recipient_uuid), GREATEST(...)).

An ordered index there would leave the race that actually matters open. Two users clicking "connect" on each other at the same instant both pass request_connection/2's pre-check (connected?/2 finds no accepted row; each direction-specific pending lookup finds nothing) and both insert. The damage is not cosmetic:

• the next request auto-accepts one row and leaves the other as a live pending request between two already-connected users;
• remove_connection/2 then deletes only the accepted row and leaves that ghost behind;
• get_accepted_connection/2 uses Repo.one/1, so a pair accepted twice raises Ecto.MultipleResultsError.

Nothing legitimately needs both directions at once: a mutual request updates the existing row to accepted rather than inserting a reverse one, and a removed connection deletes its row, freeing the pair.

The expression index is still reported under its own name in a 23505, so the schema's existing unique_constraint(name:) keeps working with no change — the field list only decides where the error is attached.

De-duplication

Existing duplicates are removed first, or CREATE UNIQUE INDEX fails. Follows and blocks keep the smallest uuid (UUIDv7 is time-ordered, so that is the row written first). Connections collapse the unordered pair and rank accepted above pending before falling back to that rule — the two can only coexist through the race being closed, and dropping the accepted row for an older pending request would disconnect two connected users. The *_history tables are untouched.

Verification

On a scratch database through PhoenixKit.Squash.MigrationRunner (it applies or undoes a single version, which the chain wrapper cannot):

Step	Result
Fresh install	3 indexes created
Undo V188 — the state every existing install is in	0 indexes
Seed same-direction and cross-direction duplicates	2 / 2 / 3 rows
Re-apply over dirty data	1 / 1 / 1 — earliest kept, accepted preserved
Duplicate follow / cross-direction connection	both refused, 23505 under the right index
Reverse follow (directed)	still inserts, as it must
Apply twice more	nothing changes

Manifest: three objects hand-declared in expected_schema.ex, shapes transcribed from a real V188 database (pg_get_indexdef, pg_index.indisunique, pg_opclass) — including the expression keys rather than column names; chain_hash restamped over the 54 shipped files. s7/s8 skip here (they need a generated manifest, and the generator aborts on the pre-existing slug-function mismatch the V184 note records), so the equivalent was used: the repair planner reports no V188 findings on a freshly-migrated database, and after dropping one index reports "comment claims V188 but V188 is the first version whose objects are not all present".

Gates:mix phoenix_kit.release_check passes every migration check (current_version/0 == v188.ex, V135..V188 contiguous, chain_hash matches 54 files). mix precommit clean. Full suite green.

hand_declared_manifest_test.exs covers these objects structurally (it pins the manifest against a chain-built schema for V171+). test/integration/user_connections_uniqueness_test.exs (new, 4 tests) covers what it cannot: that the indexes enforce, that the connection pair is refused in either direction, and that follows and blocks keep both directions.

Companion change

phoenix_kit_user_connections PR #9 handles the consequence: the losing insert now gets a 23505 instead of reaching the auto-accept branch, so create_pending_connection/2 surfaces :pair_exists and reconcile_pair_conflict/2 re-reads the pair once. Verified with 250 concurrent mutual-click rounds — one row per pair every time, 250 {:ok, "pending"} + 250 {:ok, "accepted"}, no caller raising.

No version bump and no CHANGELOG entry — those are yours.

---

2. PhoenixKit.TestSupport.PostgresPreflight — a shared connection check

A wrong PGUSER did not look like a wrong PGUSER. The module suites run
through the Ecto SQL sandbox, so a rejected login was queued and retried and
surfaced minutes later as a pool checkout timeout that reads like a flaky
test — nine repos had ended up documenting that as a landmine in their
AGENTS.md.

The default itself is fine and stays: falling back to $USER would break CI,
where the OS user is runner while the role is postgres. This fixes the
failure mode, not the configuration.

The helper makes one bounded, classified connection attempt and reports the
reason — credentials rejected, database missing, nothing listening, no free
slots — naming the effective host, database and username, and never the
password. It replaces each module's psql -lqt listing, which asked the wrong
question entirely: that ran as the shell's user over a unix socket and said
nothing about whether the configured role could connect over TCP.

It ships in lib/ because the sibling packages depend on core through Hex,
where a test/support directory is unreachable; the precedent is
Ecto.Adapters.SQL.Sandbox.

Two implementation details are load-bearing, and both were established by
measuring against a live server rather than from the documentation:

• It probes with Postgrex.Protocol.connect/1, not Postgrex.start_link/1.
  start_link/1 returns {:ok, pid} for a bad role, a missing database and
  a closed port — sync_connect: true does not change that — and the failure
  then happens inside the connection process, which is the original bug. Asking
  that connection for SELECT 1 returns the generic "dropped from queue after
  4000ms". Ecto.Adapters.Postgres.storage_status/1 is no better: a bad role
  gives {:error, {:error, %RuntimeError{message: "killed"}}}.
  Protocol.connect/1 is undocumented, so the call is guarded and any surprise
  degrades to "no opinion" rather than to a broken run.
• It whitelists connection keys off the repo config. Passing the config
  through would carry pool: Ecto.Adapters.SQL.Sandbox and rebuild the very
  pool whose timeout is being diagnosed.

check/1 never raises (most suites degrade to unit-only); check!/1 is for a
suite with no unit-only mode. It is a connection preflight, not a "database
ready" check — it says nothing about migrations, privileges or sandbox
ownership.

Nine tests cover it against a real server, including that a rejected role is
reported in under a second rather than as a queue timeout, and that sandbox
settings in the config are stripped. The companion PRs wire it into each
module's test_helper.exs.

---

3. Remove local paths and personal identifiers from committed docs

Absolute paths inside one developer's home directory, written into review
documents by the AI review tools themselves (they cite files by absolute path)
and into follow-up notes referencing a local agent-memory directory. Rewritten
to repo-relative paths, which is what a reader of a public repository can
actually use. No content changed beyond the paths.

🤖 Generated with Claude Code