aaron
2bf50c4558
Adds migrations/ directory with README documenting the convention (timestamped filenames, idempotent SQL, forward-only, single change per file). First migration is the Stage 3 queue routing columns added live during Phase A patches today: state_type, state_type_confidence, supersedes_prior_state, state_type_rationale, plus index on supersedes. Required by stage2_worker.py >= 2.2 and stage3_worker.py >= 2.3. Idempotent (IF NOT EXISTS), safe to re-apply. Verified by re-applying against the live DB — no changes, no errors. Closes a reproducibility gap: a fresh DB provisioned from git would crash on first Stage 2 enqueue without these columns. Now the SQL travels with the code.
BirdAI database migrations
Schema changes applied to the BirdAI Postgres database, in chronological order. Filenames are YYYYMMDD-NNN_short_description.sql where NNN is a sequence number within the day for ordering when multiple migrations land same-day.
Conventions
- Each file is idempotent: uses IF NOT EXISTS / IF EXISTS so it can be re-run safely against a database that already has the change applied. This matters because we don't track which migrations a given DB has applied (no migrations table yet — that's its own future migration).
- Each file is a single logical change: one feature, one rollout. Don't pile unrelated DDL into one file.
- Each file documents what it's for and which worker version requires it in a header comment, so the relationship between schema and code is legible from either side.
- Migrations are forward-only. No down-migrations. If a change is wrong, write a new migration that fixes it.
Applying
Against the live DB:
psql "$PG_DSN" -f migrations/YYYYMMDD-NNN_name.sql
Against a fresh DB (disaster recovery, dev clone), apply all files in order:
for f in migrations/*.sql; do
echo "Applying $f"
psql "$PG_DSN" -f "$f"
done
Pending: migrations tracking table
There is no schema_migrations table yet. Adding one is itself a migration — deferred until a second migration after this one lands and the need is real.