# NGBVD UUID Migration Notes

The UUID migration was split into safe phases because the original migration added UUID columns, unique indexes and backfilled large tables in one run. On large NGBVD tables this can lock tables and appear to run forever.

## Recommended sequence

1. Stop the hanging migration.
2. Check for a stuck MySQL process and kill it if required.
3. Apply this patch.
4. Run the lightweight column migration:

```bash
php artisan migrate --path=database/migrations/2026_06_04_000110_add_public_uuid_columns_to_core_tables.php
```

5. Backfill in controlled batches:

```bash
php artisan ngbvd:backfill-uuids --chunk=2000
```

You can run one large table at a time:

```bash
php artisan ngbvd:backfill-uuids --table=witnesses --chunk=1000
php artisan ngbvd:backfill-uuids --table=incident_data --chunk=2000
php artisan ngbvd:backfill-uuids --table=victim --chunk=2000
```

6. After all UUIDs are populated, create unique UUID indexes:

```bash
php artisan migrate --path=database/migrations/2026_06_04_000120_add_public_uuid_indexes_after_backfill.php
```

## Why this approach

- Adds columns quickly.
- Avoids long table locks during migration.
- Allows resumable UUID backfill.
- Allows processing one table at a time.
- Keeps integer primary keys intact while exposing UUIDs externally.