# Legacy OSA schema patches - NOT run by `php artisan migrate`

These migrations do not touch the MIS database. Every one of them writes to the
`osa_db` connection - the **legacy CI4 OSA database** (`osa_app` locally) that
`Modules/Osa` reads and writes directly.

They used to live in `database/migrations/`, where `php artisan migrate` ran
them automatically. That is a deployment hazard: `osa_db` has no safe fallbacks
in `config/database.php`, so on any server whose `.env` omits `OSA_DB_*`,
Laravel connects as `root` with an empty password and the whole MIS migration
run dies part-way with

    SQLSTATE[HY000] [1698] Access denied for user 'root'@'localhost'
    (Connection: osa_db, Database: osa_app)

- failing a MIS deployment over a database MIS does not own.

## Why they are not in the OSA Laravel app instead

`new-osa/backend-api` owns a **different** database (`new_osa`). It already
creates `license_download_counts`, the `progress` / `current_step` /
`draft_data` columns and an equivalent `document_requirements` table, and it
deliberately does **not** have the legacy per-stage approval columns
(`inspector_status`, `region_manager_status`, `dts_status`, `ceo_status` …),
`osa_support_details`, or the per-licence exam-scoring columns - its code
references none of them. Moving these files there would apply legacy columns to
a schema that replaced them, against the wrong database.

The legacy schema's real owner is the CI4 application, which has its own
migration system and cannot run these. So they stay here, beside the
`Modules/Osa` code that depends on them, but out of the automatic path.

## Running them

They are already applied to `osa_app`. You only need this to rebuild that schema
from scratch:

    php artisan migrate --path=database/migrations-legacy-osa --database=osa_db

`--database=osa_db` keeps the `migrations` bookkeeping table beside the schema it
describes. `OSA_DB_*` must be set in `.env` first - see
`Deployment/backend.env.example`.

## Adding to this directory

Don't, if you can avoid it. A new OSA feature belongs in
`new-osa/backend-api/Modules/*/database/migrations`, on the default connection.
Only a change to the legacy `osa_app` schema belongs here.

`tests/Feature/MigrationsStayInOwnDatabaseTest.php` fails the build if a
migration using a non-default connection reappears in `database/migrations/`.