migrations: retroactively track stage_3_queue routing columns

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.
This commit is contained in:
2026-05-01 19:10:16 +00:00
parent e7de7fb64b
commit 30beeb3a26
2 changed files with 60 additions and 0 deletions
+37
View File
@@ -0,0 +1,37 @@
# 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.