# Migration plan: HeroImages to the library's own tables (decision 13) Status: plan, not built, not run anywhere. Decided by Bryan 2026-11-17 (via SLP Software - SLS - Main): it may be built in the next step, **only after this plan with its back-up and rollback exists**, **rolled out to TEST only (never production)**, and **SLS-Main is told before anything is deployed to test**. ## Goal Give every photo one library record that does not depend on the Hero: `MediaAsset` (the photo) and `MediaUse` (where it is used), with **the same ids, hashes, set hashes and public addresses** as today. Nothing in `/media/hero//...` changes, so ASF, SLS and the golden files stay as they are. ## Why expand then contract | Phase | What | Reversible? | |---|---|---| | 0 Back-up | Back-up of the database and a listing of the media directory (below). | n/a | | 1 Expand | New tables `MediaAssets` and `MediaUses`, filled by copying `HeroImages` and `HeroSlides`. The Hero keeps reading and writing its own tables; the library reads the new tables behind a setting. | Yes: drop the two new tables, nothing else changed. | | 2 Switch | Hero reads photos from the library tables (setting on). New uploads write both (dual write) so the old tables stay complete. | Yes: switch the setting off; the old tables are complete. | | 3 Contract (a later release, after acceptance) | The Hero stops writing its own image columns; they are dropped in a separate migration. | Only from the back-up of that moment. Not part of the first rollout. | Files are never moved or renamed: the migration changes rows only, so the media directory is the same before and after. ## Mapping | `HeroImages` column | `MediaAssets` column | Note | |---|---|---| | `Id` | `Id` | Same id, so references keep working. | | `OriginalSha256`, `OriginalKey`, `SourceFormat`, `Width`, `Height`, `Bytes` | same | | | `FocusX`, `FocusY`, `Zoom` | `DefaultFocusX`, `DefaultFocusY`, `DefaultZoom` | The photo's default focus. | | `WideFocus*`, `TallFocus*` | `MediaUses` rows (one per slide use, ratios `wide` and `tall`) | The per-use crop; for a photo without a slide the default focus is enough. | | `SetHash`, `Variants` | `MediaUses.SetHash` (per use) | Unchanged values; computed by the existing formula. | | `CreatedAt`, `CreatedByUserId` | same | | | `OriginalFileName`, `LastUsedAt`, `DeletedAt` | same | Added in the media-library step (additive columns of the Hero). | | `HeroSlides` | `MediaUses` | |---|---| | `Id`, `ImageId` | `Id`, `AssetId` (module `hero`, place kind `slide`, place id = slide id) | ## Back-up (before phase 1, every environment) 1. **Database**: a full dump of the Hero database (and of the CMS database if it is one), written to a dated file outside the deploy directory, for example `mysqldump --single-transaction > hero-before-media-migration-YYYYMMDD.sql`. Keep it until the contract phase is accepted. 2. **Media directory**: nothing is moved, but a listing with sizes and hashes is saved (`find -type f -exec sha256sum {} +` to a text file) so the directory can be compared afterwards. On the Raspberry Pi a copy of the directory is also a quick option (`cp -a`), if there is room. 3. **Row counts** noted: `HeroImages`, `HeroSlides`, `HeroRetiredFiles`. ## Verification (right after phase 1, every environment) The migration job compares and **aborts** (rolls its transaction back) on any difference: - number of `MediaAssets` = number of `HeroImages` (all rows, also those in the trash); - every `HeroImages.Id`, `OriginalSha256` and `SetHash` has an identical `MediaAssets`/`MediaUses` counterpart; - number of `MediaUses` of module `hero` = number of `HeroSlides`; - a sample of ten public addresses (`/media/hero//`) is requested before and after and gives the same bytes (checked by the smoke test). ## Rollback | When | How | |---|---| | The verification fails | The migration runs in one transaction and rolls back by itself; nothing is left. | | After phase 1, before the switch | Drop `MediaUses` and `MediaAssets` (the EF `Down` migration). The Hero never read them. | | After the switch | Switch the setting back (`Media:Library:ReadFromLibrary=false`); the old tables are complete because of the dual write. Then drop the new tables if wanted. | | After the contract phase (later) | Restore the database dump taken before that migration and the media listing check. | ## Roll-out rules (from Bryan) 1. **Test only.** No production variables, no production deploy, no release branch. 2. **Tell SLS-Main before deploying to test** (they run the deploy and the smoke test). 3. Back-up first (above), on the test host too. 4. Deploy with the setting **off**, check the verification result in the log, then switch it on, then the smoke test (hero markers, `/theme-init.js`, a sample of media addresses), then Bryan checks the admin. ## Status (2026-11-17): phase 1 (expand) is built, behind a setting that is OFF Built on `feature/media-library-screen`, not yet deployed anywhere: - New module `SlpModularCms.Modules.Media` (own `MediaDbContext`, tables `MediaAssets` and `MediaUses`, additive migration `InitialCreate`; no existing table is touched). It is referenced by the three hosts, so a deploy of this code creates the two empty tables at start-up and nothing else. - `IMediaMigrationSource` (Core) and `HeroMediaMigrationSource` (Hero, read-only): the hero's photos (also those in the trash) and slides with their own ids, hashes and set hashes. - `MediaLibraryCopier`: copies and **verifies** (counts, ids, hash, key, size, set hash) in one transaction; any difference or error rolls the whole copy back and nothing is left. It MIRRORS the source, so running it again gives the same result; rows of other modules are not touched. - The copy runs only when `Media__Library__CopyOnStartup=true` (default **false**) and a failure is logged, never fatal. - Tested in memory and against a real MariaDB (migration, copy twice, rollback on a failing copy). Nothing reads from the new tables yet (phase 2, the switch, is not built). The library screen still reads the hero through the usage provider. ### Roll-out on TEST (needs SLS-Main to be told first) 1. Back-up (database dump and media listing) as above. 2. Deploy the branch with `Media__Library__CopyOnStartup` unset: the two empty tables appear; check the log for the Media migration. 3. Set `Media__Library__CopyOnStartup=true` and restart: the log says `Media library copy verified: N photos and M uses from hero` (or the error and the rollback). 4. Rollback at any point: set it back to false (the tables stay, unused) or drop `MediaUses` and `MediaAssets`. 5. Never on production. ### Still to build (phases 2 and 3) The switch (`Media:Library:ReadFromLibrary`, dual write of new uploads, library reading from the new tables) and the contract phase. They need Bryan's acceptance of the copy on test first.