# 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.