Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
8.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.
Test host: what to check around the copy (prepared 2026-11-17; the copy is NOT switched on yet)
Deploy without the copy (decided on assumption by SLS-Main, Bryan away): the test deploy of the branch carries two additive database changes, the Hero migration AddMediaLibraryColumns (three nullable columns) and the empty tables of the Media module. No separate database dump is taken on the Raspberry Pi (SLS-Main cannot make one); the assumption is that the test data can be rebuilt with the seed scripts and that both changes are additive. Bryan checks this assumption later.
After that deploy, check in the log:
Applying migration '..._AddMediaLibraryColumns'andApplying migration '..._InitialCreate'(Media) appear once, no error;- the Hero admin still opens, a photo can be uploaded and a slide saved (smoke test), and
/media/hero/<setHash>/...addresses still answer; Media__Library__CopyOnStartupis NOT set: no lineMedia library copy verifiedappears.
To switch the copy on (only after Bryan's agreement):
- Make a database dump first if it can be done, and note the number of rows:
SELECT COUNT(*) FROM HeroImages; SELECT COUNT(*) FROM HeroSlides;. - Set the environment variable
Media__Library__CopyOnStartup=trueon the test host and restart the application. - The log must say
Media library copy verified: N photos and M uses from hero.with N equal to theHeroImagescount and M equal to theHeroSlidescount. An error lineThe media library copy failed and was rolled backmeans nothing was copied. - Check:
SELECT COUNT(*) FROM MediaAssets; SELECT COUNT(*) FROM MediaUses;equals the same counts; the library screen still shows the same photos (it still reads the hero). - Switch it off again (remove the variable, restart) when done: the copy can be repeated at any time; it is a mirror.
Rollback: remove the variable (the tables stay, unused), or drop the tables with the EF Down migration of the Media module; the Hero's own tables are never changed by the copy.