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.
38 lines
1.4 KiB
Markdown
38 lines
1.4 KiB
Markdown
# 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.
|