fix(BA-6913): reconcile indexes that only exist on migrated databases

[jopemachine]

📚 Stacked PRs

• fix(BA-6913): reconcile indexes that only exist on migrated databases #12907 — BA-6913 fix: indexes that only exist on migrated databases ← you are here
• fix(BA-6914): give the three drifting FKs one name on both install paths #12910 — BA-6914 fix: one FK constraint name on both install paths
• fix(BA-6915): drop the column default before retyping sessions.result #12912 — BA-6915 fix: drop the column default before retyping sessions.result

Merge in order, bottom-up. Each PR is based on the one above it, so its diff shows only its own layer.

Problem

The schema is defined twice, and nothing checks that the two agree:

	fresh install	existing install
command	mgr schema oneshot	alembic upgrade head
schema from	SQLAlchemy model metadata → create_all → stamp head	the migration files
migrations run	none at all	all

Three migrations create an index the matching model never declared, so it exists only on migrated databases. Verified on a DB built at head by oneshot: none of the three is present, and no later migration drops them.

Convergence has two directions

Which way each index goes depends on whether it earns its write cost, so each was checked individually rather than fixed by pattern:

column	FK	filtered / joined / ordered by?	direction
role_invitations.invitee_user_id	yes — ON DELETE CASCADE	the cascade must scan for them	create
prometheus_query_presets.category_id	yes — ON DELETE SET NULL	the category delete must scan for them	create
vfolders.creator_id	no	never — only written and selected, nowhere in src/ai/backend/	drop

role_invitations.invitee_user_id is the one that bites: on a fresh install every user deletion scans role_invitations. uq_role_invitations_active cannot substitute — it is partial (WHERE state != 'accepted'), so it excludes exactly the rows a cascade must find.

vfolders.creator_id goes the other way. Nothing reads it, so the index b4e7f1a2c3d5 created costs a write on every vfolder and saves nothing. Declaring it on the model to match would have spread the cost to every install; instead its creation is removed and migrated databases have it dropped.

Fix

1. Declare the two FK-backed indexes on the models (index=True reproduces the migrations' exact ix_<table>_<column> names).
2. Remove the create_index from b4e7f1a2c3d5.
3. Add b2f7c1a94e30 to reconcile databases already out there — creates the two, drops the one. Existence checks make every statement a no-op where the DB already agrees; its downgrade is a no-op, since undoing it would only put the drift back.
4. Drop the redundant drop_index calls in all three: the following drop_column/drop_table removes the index anyway, so naming it first only broke installs that never had it. This is independent of the model change — b4e7f1a2c3d5's downgrade passes on a fresh install with no such index.

Verification

All against real databases; the dev DB was only ever read.

Fresh install — exactly the intended set: the two FK indexes present, ix_vfolders_creator_id absent.

Old oneshot install (schema built from main's models, stamped at the old head aa27f1d5cd35):

	FK indexes	useless vfolder index
before upgrade head	0 of 2	0
after	2 of 2	0

Migrated DB carrying the useless index:

	FK indexes	useless vfolder index
before upgrade head	2 of 2	1
after	2 of 2	0

Re-running after a downgrade produces no errors.

Edited b4e7f1a2c3d5 round-trip: downgrade drops creator_id; re-upgrade restores the column and does not create the index.

Downgrade on a fresh install (stamp the revision, run only its downgrade):

migration	main	this PR
ad7acfe8aa1c	FAILED — index "ix_role_invitations_invitee_user_id" does not exist	OK
b4e7f1a2c3d5	FAILED — index "ix_vfolders_creator_id" does not exist	OK
a3b4c5d6e7f8	FAILED — index "ix_prometheus_query_presets_category_id" does not exist	still fails ¹

¹ Honest result: clearing the index error on a3b4c5d6e7f8 exposes a second, different defect underneath — its downgrade also drops fk_prometheus_query_presets_category_id, but a fresh install names that constraint by the metadata convention, which exceeds PostgreSQL's 63-char identifier limit and comes out truncated and hash-suffixed as fk_prometheus_query_presets_category_id_prometheus_quer_8a51. That is the FK-naming drift class (BA-6914, also affects cd067180a8b1 and c7f2a8e31b04) — those constraints are enforced on both paths, only the names differ. This PR does not claim to fix it.

Found while surveying the downgrade chain for #12881.

🤖 Generated with Claude Code