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.
1.4 KiB
1.4 KiB
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.