diff --git a/migrations/20260501-001_stage_3_queue_routing_columns.sql b/migrations/20260501-001_stage_3_queue_routing_columns.sql new file mode 100644 index 0000000..72d7ed3 --- /dev/null +++ b/migrations/20260501-001_stage_3_queue_routing_columns.sql @@ -0,0 +1,23 @@ +-- 20260501-001 — Stage 3 queue routing columns for Phase A bulk-vs-single-episode routing +-- +-- Adds four columns and one index to stage_3_queue, written by Stage 2 v2.2 +-- and read by Stage 3 v2.3 to choose between bulk and single-episode ingest +-- pathways. See architecture doc and Phase A handoff (2026-05-01) for design. +-- +-- Required by: +-- scripts/stage2_worker.py >= 2.2 +-- scripts/stage3_worker.py >= 2.3 +-- +-- Idempotent: safe to re-apply against a database where the columns already +-- exist (was applied live before this file was created). + +ALTER TABLE stage_3_queue + ADD COLUMN IF NOT EXISTS state_type TEXT, + ADD COLUMN IF NOT EXISTS state_type_confidence TEXT, + ADD COLUMN IF NOT EXISTS supersedes_prior_state BOOLEAN, + ADD COLUMN IF NOT EXISTS state_type_rationale TEXT; + +-- Index on the routing signal — Stage 3 reads this on every dequeue, +-- and observability queries (item 6: routing_decisions) will filter on it. +CREATE INDEX IF NOT EXISTS stage_3_queue_supersedes_idx + ON stage_3_queue (supersedes_prior_state); diff --git a/migrations/README.md b/migrations/README.md new file mode 100644 index 0000000..448cf6e --- /dev/null +++ b/migrations/README.md @@ -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.