Guard against model/migration drift between datagov-data-access and the harvester

[cody-seibert-gsa]

Models live in datagov-data-access; Alembic migrations live here. Nothing enforces that a model column added there gets a migration here, so a version bump can land a column the database does not have. Any query selecting the model then fails with column ... does not exist.

This has now happened twice with the same column

harvest_job.records_warned was added to the model in data-access 1.1.0.

1. PR Update datagov-data-access to 1.1.0 #794 bumped the pin to 1.1.0 and added the migration (b3f4a9c1d7e2).
2. Independently, PR Add ON DELETE CASCADE to harvest source/job/record foreign keys #793 hit the missing column while testing and wrote its own migration for it (f4a2b8c15d93).

Both landed. After #793 merged main, the branch had two Alembic heads and two migrations adding the same column. flask db upgrade runs on every deploy (app-start.sh:9) and fails on multiple heads, so the branch would have broken deploys. Fixed in 9a4f5c9 by dropping the duplicate and relinking to a single head.

So the failure mode is not only "migration missing" — it is also "two people write the same migration and collide."

Suggested guards

• CI check for multiple heads. Cheap and catches the collision class directly:

  flask db heads   # fail the build if it reports more than one
  

• CI check that models match migrations. alembic check (or autogenerate-and-diff) fails when a model column has no corresponding migration, catching the drift at the bump rather than in production.
• Checklist item on data-access bump PRs: state explicitly whether the release added or changed columns, and link the migration if so.

The first two are the durable fixes; the multiple-heads check alone would have caught this instance in CI.

Reference

• Column: harvest_job.records_warned, server_default="0", added in data-access 1.1.0
• Migration on main: migrations/versions/b3f4a9c1d7e2_add_records_warned_to_harvest_job.py
• Related: Add ON DELETE CASCADE to harvest source/job/record foreign keys #793, Update datagov-data-access to 1.1.0 #794

[rshewitt]

interesting, so even if the data-access repo just contained db models, for example, we'd still run into this situation where...

1. a db change occurs following by a new release (or no release and simply merge into main if ditching releasing all together)
2. multiple developers working on harvester simultaneously who integrate that change run migration locally causing multiple separate migrations leading to multiple heads.

well, i'm honestly surprised we found such a big issue with this new approach already but i'm glad we found it. we already intended to move back some of the functionality but this involves models which we actually intended to keep there. the way i see it is we can implement a guard against this issue (per @cody-seibert-gsa recommendation) or we can switch back entirely. i can say that switching back entirely will not take nearly as much time. probably a day or two.