2026-08-26 · run 2026-08-26-index-precondition-anatomy

what Keycloak's index check actually checks, and the upgrade it kills

Why this run existed

Run A established that Keycloak's index changeset is guarded by a name-based precondition and that the 300,000-row skip reads a planner statistic. It left four questions open, and each was cheap to answer once reltuples was known to be a lever. Answering them turned up a failure mode none of the previous twenty-one records contains: an upgrade that dies mid-migration and leaves the server unable to start.

Environment

Identical to 2026-08-25-runA-indexes-manually-created — 2,000,003 users, baseline-26.0.0-sqlseed-2m, Postgres 16 at stock settings, Hetzner CCX33 (8 vCPU dedicated, 30GB RAM, local NVMe), JVM -Xms1g -Xmx4g, official image, start with an external DB. Every leg begins with a verified restore of that baseline, so the legs are comparable to each other and to Run A's.

autovacuum is disabled on USER_ENTITY in the legs that write to pg_class, so an analyze cannot silently undo the setup between the write and the upgrade.

Results

Breakage observed

An index name collision on an unrelated table fails the upgrade and blocks startup

• Symptom: relation "idx_user_created_timestamp" already exists, server refuses to start, changelog stops at 187/211 with migration_model at 26.0.0.
• Evidence: A7c, quoted above.
• Cause: confirmed — per-schema index names against a per-table precondition.
• Fix or workaround: rename or drop the colliding index, restart. The half-applied changelog resumes, as it did in S8 and S14.
• Would this hit a customer? Config-dependent and latent. It needs someone to have created an index carrying a Keycloak index name on another table — which our own runbook makes likelier, since it hands operators those exact names to paste. It then waits for a build to be attempted.

DatabaseIndexChecker reports a healthy database when the index is on the wrong table

• Symptom: the checker runs and emits nothing, while the index the changeset defines does not exist on the table it names.
• Evidence: §3 above; Running database index checker present, no Missing database index line, pg_indexes shows the index on realm.
• Cause: confirmed — the checker matches on index name alone.
• Fix: compare definitions, per table, as bin/index-audit.sh does.
• Would this hit a customer? Anyone relying on Keycloak's own index check.

Verification