Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
5.4 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.
What is built first (next step, when this plan is accepted)
- A new module
SlpModularCms.Modules.Mediawith its ownDbContext, the tablesMediaAssetsandMediaUsesand an additive EF migration (no existing table touched), with tests. - The copy-and-verify job (idempotent, safe to run twice) behind a setting; unit and in-memory tests, and a test against MariaDB.
- The library reading from the new tables behind
Media:Library:ReadFromLibrary(default off).
Nothing in steps 1 to 3 runs without the setting, so a deploy of that code alone changes no data except the new, empty tables.