Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6.8 KiB
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/<setHash>/... 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)
- 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 <database> > hero-before-media-migration-YYYYMMDD.sql. Keep it until the contract phase is accepted. - Media directory: nothing is moved, but a listing with sizes and hashes is saved (
find <Media__Directory> -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. - 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 ofHeroImages(all rows, also those in the trash); - every
HeroImages.Id,OriginalSha256andSetHashhas an identicalMediaAssets/MediaUsescounterpart; - number of
MediaUsesof modulehero= number ofHeroSlides; - a sample of ten public addresses (
/media/hero/<setHash>/<file>) 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)
- Test only. No production variables, no production deploy, no release branch.
- Tell SLS-Main before deploying to test (they run the deploy and the smoke test).
- Back-up first (above), on the test host too.
- 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(ownMediaDbContext, tablesMediaAssetsandMediaUses, additive migrationInitialCreate; 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) andHeroMediaMigrationSource(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)
- Back-up (database dump and media listing) as above.
- Deploy the branch with
Media__Library__CopyOnStartupunset: the two empty tables appear; check the log for the Media migration. - Set
Media__Library__CopyOnStartup=trueand restart: the log saysMedia library copy verified: N photos and M uses from hero(or the error and the rollback). - Rollback at any point: set it back to false (the tables stay, unused) or drop
MediaUsesandMediaAssets. - 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.